Model
Module: xfea.model.model
Model(
description: Optional[str] = None,
author: Optional[str] = None,
units: Optional[str] = 'SI_mm',
**kwargs,
)
A finite element model: its parts (with their nodes and elements), supports, couplings, interfaces and problems.
Parameters
| Name | Type | Description |
|---|---|---|
| description | str, optional | A description of the model, written at the top of the input file. |
| author | str, optional | The author’s name, written at the top of the input file. |
| units | {“SI_mm”, “SI”}, optional | The unit system of the model’s physical constants (gravity, Stefan-Boltzmann, absolute zero). "SI_mm" (the default) is mm, t, s, N, MPa, with g = 9810 mm/s²; "SI" is m, kg, s, N, Pa. Fixed once the model is built. |
| name | str, optional | The model’s name, generated if not given; it names the folder of the results. |
Attributes
| Name | Type | Description |
|---|---|---|
| description | str | None | The description of the model. |
| author | str | None | The author’s name. |
| units | str | The unit system of the physical constants. |
| constants | dict | The physical constants: g, stefan_boltzmann, absolute_zero, gas_constant. |
| parts | PartsGroup |
The parts of the model. |
| nodes, elements | NodesGroup, ElementsGroup |
Every node and every element of the parts. |
| bcs, ics | FieldsGroup |
The supports and the initial conditions, each a field: a condition and its nodes. |
| constraints | ConstraintsGroup |
The constraints, such as rigid couplings. |
| spring_links | list[SpringLink] |
The springs between nodes, in the order added. |
| interfaces | InterfacesGroup |
The interfaces between parts (contacts and ties). |
| materials, sections | MaterialsGroup, SectionsGroup |
The materials and sections the elements use. |
| problems | set[Problem] |
The problems added to the model. |
| path | Path | None |
The folder where the problems’ results are stored. |
Guidance (model)
- xfea does not enforce units: keep them consistent. Common: mm, N, MPa (N/mm2), tonnes; steel density 7.85e-9 t/mm3, g = 9810 mm/s2.
- Each piece is a part with its own nodes. Pieces that touch or are welded are joined by an interface between their parts (see contact), not by sharing nodes.
- Call
model.check()before solving: it lists what the solver would get wrong without saying so (every solve logs it too).
Properties
absolute_zerofloatread-only
The temperature value that is absolute zero: 0 when temperatures are in kelvin, -273.15 in °C.
amplitudesread-only
The amplitudes (time variations) the thermal interfaces’ temperatures use, each once.
bb_centerPointread-only
The centre of the model’s bounding box; raises AttributeError if it has none.
bcsFieldsGroupread-only
The supports of the model (and imposed temperatures), each a field: a condition and its nodes.
bcs_nodesdict[BoundaryConditionBase, NodesGroup]read-only
{condition: nodes} for each support of the model.
bottom_planePlaneread-only
The plane of the bottom face of the model’s bounding box; raises AttributeError if it has none.
boundary_facesFacesGroupread-only
All exterior boundary faces, aggregated across parts.
Each part computes its own boundary lazily and caches the result
(see boundary_faces). The model-level aggregator
is just a concatenation — cheap when the per-part cache is warm.
bounding_boxOptional[Box]read-only
The box, aligned with the global axes, around every part; None if it cannot be worked out.
centerPointread-only
The mean of the locations of every node of the model.
centroidPointread-only
The centroid of the model: the parts’ centroids weighted by the parts’ weights.
connectorsConnectorsGroupread-only
The connectors of the model.
constantsdictread-only
The physical constants of the model’s unit system: g, stefan_boltzmann, absolute_zero, gas_constant.
constraintsConstraintsGroupread-only
The constraints of the model, such as rigid couplings.
elementsElementsGroupread-only
Every element of the model’s parts, as a new group.
fieldsFieldsGroupread-only
Every field of the model: supports, initial conditions and connectors.
gfloatread-only
The gravitational acceleration in the model’s units: 9810 mm/s² for "SI_mm", 9.80665 m/s² for "SI".
graphnx.DiGraphread-only
The graph of the model: the model and its parts as nodes, joined by “contains” edges.
groupsSet[GroupBase]read-only
Every group registered to the model: the parts, fields, interfaces and the groups they use.
icsFieldsGroupread-only
The initial conditions of the model, each a field: a condition and its nodes or elements.
ics_nodesdict[InitialConditionBase, NodesGroup]read-only
{condition: nodes} for each initial condition of the model (elements, for an initial stress).
interactionsInteractionsGroupread-only
The contact behaviours of the model’s interfaces, as a group.
Only behaviors that are InteractionBase are collected —
surface ConstraintBase behaviors (TieConstraint etc.)
ride on interfaces too, but they are not interactions and
must be skipped here so downstream group typing doesn’t reject
them.
interfacesInterfacesGroupread-only
The interfaces between parts (contacts and ties).
keyAny | Noneread-only
The object’s key (its number) in what it is registered to; None until it is given one.
materialsMaterialsGroupread-only
The materials the model’s elements use, each once.
namestr
The object’s name.
nodesNodesGroupread-only
Every node of the model’s parts, as a new group.
part_materialsDict[PartBase, Set[MaterialBase]]read-only
{part: materials}: the materials each part’s elements use (rigid parts left out).
part_sectionsDict[PartBase, Set[SectionBase]]read-only
{part: sections}: the sections each part’s elements use (rigid parts left out).
partsPartsGroupread-only
The parts of the model.
pathOptional[Path]
The folder of the model’s results; set to a folder, it becomes that folder’s subfolder named after the model.
pointslist[Point]read-only
The locations of every node of the model, as points.
problemsSet[Problem]read-only
The problems added to the model.
registrationAny | None
The object this one is registered to (a part, a model, a step, …), or None.
section_elementsDict[SectionBase, ElementsGroup]read-only
{section: elements}: the model’s elements grouped by their section.
sectionsSectionsGroupread-only
The sections the model’s elements use, each once.
spring_linkslistread-only
The springs between nodes (SpringLink), in the order added.
stefan_boltzmannfloatread-only
The Stefan-Boltzmann constant σ in the model’s units (power per area per K⁴).
top_planePlaneread-only
The plane of the top face of the model’s bounding box; raises AttributeError if it has none.
uidUUID | Noneread-only
The object’s unique id, a UUID.
volumefloatread-only
The total volume of the parts’ elements, in the model’s volume unit (mm³ for mm).
Methods
add_bcs(bc_fields)→MechanicalBCField | List[MechanicalBCField]
add_bcs(
bc_fields: MechanicalBCField | List[MechanicalBCField],
) -> MechanicalBCField | List[MechanicalBCField]
Add supports to the model, each a field: a boundary condition and the nodes it holds.
The add_*_bc methods build the field; this adds one built by hand,
such as one with a GeneralBC.
Parameters
| Name | Type | Description |
|---|---|---|
| bc_fields | MechanicalBCField | list[MechanicalBCField] |
The field, or a list of them. |
Returns
| Name | Type | Description |
|---|---|---|
class:xfea.model.MechanicalBCField | list[MechanicalBCField] |
What was given. |
add_clampXX_bc(nodes, frame=None, **kwargs)
add_clampXX_bc(nodes: Union[list[Node], NodesGroup], frame: Frame = None, **kwargs)
Hold the translations of nodes and their rotation about x; the rotations about y and z stay free (ClampBCXX).
Parameters
| Name | Type | Description |
|---|---|---|
| nodes | list[Node] | NodesGroup |
The nodes to hold; they must be in parts of this model. |
| frame | Frame, optional |
The frame whose local axes the support’s directions are along, or None for the global axes. |
Returns
| Name | Type | Description |
|---|---|---|
class:xfea.model.MechanicalBCField |
The support: the condition and its nodes. |
add_clampYY_bc(nodes, frame=None, **kwargs)
add_clampYY_bc(nodes: Union[list[Node], NodesGroup], frame: Frame = None, **kwargs)
Hold the translations of nodes and their rotation about y; the rotations about x and z stay free (ClampBCYY).
Parameters
| Name | Type | Description |
|---|---|---|
| nodes | list[Node] | NodesGroup |
The nodes to hold; they must be in parts of this model. |
| frame | Frame, optional |
The frame whose local axes the support’s directions are along, or None for the global axes. |
Returns
| Name | Type | Description |
|---|---|---|
class:xfea.model.MechanicalBCField |
The support: the condition and its nodes. |
add_clampZZ_bc(nodes, frame=None, **kwargs)
add_clampZZ_bc(nodes: Union[list[Node], NodesGroup], frame: Frame = None, **kwargs)
Hold the translations of nodes and their rotation about z; the rotations about x and y stay free (ClampBCZZ).
Parameters
| Name | Type | Description |
|---|---|---|
| nodes | list[Node] | NodesGroup |
The nodes to hold; they must be in parts of this model. |
| frame | Frame, optional |
The frame whose local axes the support’s directions are along, or None for the global axes. |
Returns
| Name | Type | Description |
|---|---|---|
class:xfea.model.MechanicalBCField |
The support: the condition and its nodes. |
add_connector(connector)→ConnectorField
add_connector(connector: ConnectorBase | ConnectorField) -> ConnectorField
Add a connector to the model.
A ConnectorBase is wrapped in a
ConnectorField; a field is added as it is.
Parameters
| Name | Type | Description |
|---|---|---|
| connector | ConnectorBase | ConnectorField |
The connector (or connector field) to add. |
Returns
| Name | Type | Description |
|---|---|---|
class:xfea.model.fields.ConnectorField |
The added connector field. |
add_constraint(constraint)→ConstraintField
add_constraint(constraint: ConstraintBase | ConstraintField) -> ConstraintField
Add a constraint, such as a RigidCoupling, to the model.
A ConstraintBase is wrapped in a
ConstraintField; a field is added as it is.
Parameters
| Name | Type | Description |
|---|---|---|
| constraint | ConstraintBase | ConstraintField |
The constraint (or constraint field) to add. |
Returns
| Name | Type | Description |
|---|---|---|
class:xfea.model.fields.ConstraintField |
The added constraint field. |
add_constraints(constraints)→list[ConstraintField]
add_constraints(
constraints: list[ConstraintBase | ConstraintField],
) -> list[ConstraintField]
Add constraints to the model, as add_constraint() does each.
Parameters
| Name | Type | Description |
|---|---|---|
| constraints | list[ConstraintBase | ConstraintField] |
The constraints to add. |
Returns
| Name | Type | Description |
|---|---|---|
| list[ | class:xfea.model.fields.ConstraintField] |
The added constraint fields. |
add_fix_bc(nodes, frame=None, **kwargs)
add_fix_bc(nodes: Union[list[Node], NodesGroup], frame: Frame = None, **kwargs)
Hold nodes fixed: all three translations and all three rotations (FixedBC).
Parameters
| Name | Type | Description |
|---|---|---|
| nodes | list[Node] | NodesGroup |
The nodes to hold; they must be in parts of this model. |
| frame | Frame, optional |
The frame whose local axes the support’s directions are along, or None for the global axes. |
Returns
| Name | Type | Description |
|---|---|---|
class:xfea.model.MechanicalBCField |
The support: the condition and its nodes. |
add_group(group)→Any
add_group(group: GroupBase) -> Any
Register a group to the model.
Parameters
| Name | Type | Description |
|---|---|---|
| group | GroupBase |
The group, such as a PartsGroup. |
Returns
| Name | Type | Description |
|---|---|---|
class:xfea.model.GroupBase |
The group. |
add_groups(groups)→list[GroupBase]
add_groups(groups: list[GroupBase]) -> list[GroupBase]
Register groups to the model, as add_group() does each.
Parameters
| Name | Type | Description |
|---|---|---|
| groups | list[GroupBase] |
The groups. |
Returns
| Name | Type | Description |
|---|---|---|
| list[ | class:xfea.model.GroupBase] |
The groups. |
add_ics_field(ic_field)→InitialConditionFieldBase
add_ics_field(ic_field: InitialConditionFieldBase) -> InitialConditionFieldBase
Add an initial condition field to the model: an initial temperature or stress and its nodes or elements.
Parameters
| Name | Type | Description |
|---|---|---|
| ic_field | InitialTemperatureField | InitialStressField |
The field. |
Returns
| Name | Type | Description |
|---|---|---|
class:xfea.model.InitialTemperatureField | InitialStressField |
The field. |
add_ics_fields(ics_fields)→list[InitialConditionFieldBase]
add_ics_fields(
ics_fields: list[InitialConditionFieldBase],
) -> list[InitialConditionFieldBase]
Add initial condition fields to the model, as add_ics_field() does each; returns them.
add_interaction(interaction)→InteractionBase
add_interaction(interaction: InteractionBase) -> InteractionBase
Add an interaction (a contact behaviour) to the model.
Interfaces carry their behaviour themselves (detect_interfaces()):
this is for one used without an interface.
Parameters
| Name | Type | Description |
|---|---|---|
| interaction | InteractionBase |
The interaction to add. |
Returns
| Name | Type | Description |
|---|---|---|
class:xfea.model.InteractionBase |
The interaction. |
add_interactions(interactions)→list[InteractionBase]
add_interactions(interactions: list[InteractionBase]) -> list[InteractionBase]
Add interactions to the model, as add_interaction() does each.
Parameters
| Name | Type | Description |
|---|---|---|
| interactions | list[InteractionBase] |
The interactions to add. |
Returns
| Name | Type | Description |
|---|---|---|
| list[ | class:xfea.model.InteractionBase] |
The interactions. |
add_interface(interface)→InterfaceBase
add_interface(interface: InterfaceBase) -> InterfaceBase
Add an interface between parts (a contact or a tie) to the model.
detect_interfaces() finds and adds them; this adds one built by hand.
Parameters
| Name | Type | Description |
|---|---|---|
| interface | InterfaceBase |
The interface. |
Returns
| Name | Type | Description |
|---|---|---|
class:xfea.model.InterfaceBase |
The interface. |
add_interfaces(interfaces)
Add interfaces to the model, as add_interface() does each; returns them.
add_part(part=None, **kwargs)→PartBase
add_part(part: Optional[PartBase] = None, **kwargs) -> PartBase
Add a part to the model, or build one from keyword arguments and add it.
Parameters
| Name | Type | Description |
|---|---|---|
| part | Part | RigidPart, optional |
The part to add, or None to build a Part from the keyword arguments (a RigidPart if rigid=True). |
| **kwargs | The new part’s arguments, such as name, when part is None. |
Returns
| Name | Type | Description |
|---|---|---|
class:xfea.model.Part | RigidPart |
The part added. |
add_parts(parts)→list[PartBase]
add_parts(parts: list[PartBase]) -> list[PartBase]
Add parts to the model, as add_part() does each.
Parameters
| Name | Type | Description |
|---|---|---|
| parts | list[Part] |
The parts to add. |
Returns
| Name | Type | Description |
|---|---|---|
| list[ | class:xfea.model.Part] |
The parts added. |
add_parts_from_mesh(path, parts)→list
add_parts_from_mesh(path, parts: list) -> list
Read a finite element mesh from a file into parts: gmsh .msh, Abaqus .inp, VTK, Salome .med.
Any format meshio reads. Each part takes the cells its section fits (solid sections tetrahedra and bricks, shell and membrane sections triangles and quads, beam and truss sections lines), optionally only those of one of the file’s element sets (an Abaqus elset, a gmsh physical group). The file’s node sets, and its sets of cells a part does not take (a gmsh physical surface on a solid), become node groups on the parts, by name, for supports and loads.
Parameters
| Name | Type | Description |
|---|---|---|
| path | str | The mesh file. |
| parts | list[dict] | One entry per part: {"name", "section"} and optionally "set", the element set it takes (needed when there is more than one part), and "orientation", the local y axis of beams. |
Returns
| Name | Type | Description |
|---|---|---|
| list[ | class:xfea.model.Part] |
The new parts, in the order of parts. Parts keep their own nodes, even where their cells share points in the file: join them with a tie, contact or coupling. |
Guidance (solids)
- A mesh made elsewhere (FreeCAD’s FEM workbench, gmsh, Salome) comes in with
model.add_parts_from_mesh: name an element set per part, so each solid is its own part, and use the file’s node sets for supports and loads.
add_parts_from_step(path, parts, element_order=2, refine_holes=None, hole_reach=None, hole_radius=None, zones=None, refine=None, engine=None)→list
add_parts_from_step(
path,
parts,
element_order: int = 2,
refine_holes: Optional[float] = None,
hole_reach: Optional[float] = None,
hole_radius: Optional[float] = None,
zones: Optional[list] = None,
refine: Optional[list] = None,
engine=None,
) -> list
Mesh the solids of a STEP file (an assembly), each into a part of its own.
Parameters
| Name | Type | Description |
|---|---|---|
| path | str | The STEP file. |
| parts | list[dict] | One entry per part: {"name", "section", "size"} and optionally "solid", the solid’s name in the file (a CAD tool’s body label, as FreeCAD writes it), or "at", a point inside it. Entries with neither take the remaining solids in the file’s order. |
| element_order | int, optional | 2 (quadratic tetrahedra, the default) or 1 (linear: far too stiff in bending, for plates). |
| refine_holes | float, optional | The element size on every curved face (the walls of bolt holes, rounds), growing to the part’s size over hole_reach (default 4 x refine_holes). |
| hole_reach | float, optional | How far from a curved face the element size grows back to the part’s size, or None for 4 x refine_holes. |
| hole_radius | float, optional | Refine only curved faces of this radius or less: the holes, not a rolled section’s root fillets, which run the member’s length. |
| zones | list[dict], optional | Finer regions across the parts, each {"box": [low, high], "size": s} and optionally "reach", how far outside the box the size grows back (default 4 x size): a column coarse along its length, fine at the joint. |
| refine | list[Refine], optional |
Finer meshes on what Select picks, across the parts: a hole, an edge, a face, a box. refine_holes and zones are two of these, written short. |
| engine | str, optional | The meshing engine, one that meshes assemblies (gmsh), or None for the first such engine installed. |
Returns
| Name | Type | Description |
|---|---|---|
| list[ | class:xfea.model.Part] |
The new parts, in the order of parts. Solids that touch keep their own nodes on the shared face: join them with contact or a tie. |
Guidance (solids)
- Build the assembly in CAD (FreeCAD, or gmsh’s OpenCASCADE), one solid per part, and write it as
STEP; pick each part’s solid by its body name (
"solid"). The parts are meshed apart: join them by interfaces withmethod="face_intersection". - For bolt holes,
refine=[Refine(Select.holes(radius_max=...), size=...)]: a hole is a round face with its material away from its axis, going at least half way round, so pins and a section’s root fillets are left out.zoneskeep long members coarse and the joint fine. - See what a selection picks first:
xfea.meshing.describe(path, select=...).
add_pin_bc(nodes, frame=None, **kwargs)
add_pin_bc(nodes: Union[list[Node], NodesGroup], frame: Frame = None, **kwargs)
Hold nodes pinned: the three translations held, the rotations free (PinnedBC).
Parameters
| Name | Type | Description |
|---|---|---|
| nodes | list[Node] | NodesGroup |
The nodes to hold; they must be in parts of this model. |
| frame | Frame, optional |
The frame whose local axes the support’s directions are along, or None for the global axes. |
Returns
| Name | Type | Description |
|---|---|---|
class:xfea.model.MechanicalBCField |
The support: the condition and its nodes. |
add_problem(problem=None, **kwargs)→Problem
add_problem(problem: Optional[Problem] = None, **kwargs) -> Problem
Add a problem (what happens to the model: its steps and loads) to the model, or build one and add it.
Parameters
| Name | Type | Description |
|---|---|---|
| problem | Problem, optional |
The problem to add, or None to build one from the keyword arguments. |
| **kwargs | The new problem’s arguments, such as name, when problem is None. |
Returns
| Name | Type | Description |
|---|---|---|
class:xfea.problem.Problem |
The problem added. |
add_problems(problems)→list[Problem]
add_problems(problems: list[Problem]) -> list[Problem]
Add problems to the model, as add_problem() does each.
Parameters
| Name | Type | Description |
|---|---|---|
| problems | list[Problem] |
The problems to add. |
Returns
| Name | Type | Description |
|---|---|---|
| list[ | class:xfea.problem.Problem] |
The problems added. |
add_rigid_coupling(reference, nodes)→ConstraintField
add_rigid_coupling(
reference: Node,
nodes: Union[list[Node], NodesGroup],
) -> ConstraintField
Make nodes follow reference as one rigid body (RigidCoupling).
Parameters
| Name | Type | Description |
|---|---|---|
| reference | Node |
The node the others follow, e.g. a beam’s end node. |
| nodes | list[Node] or NodesGroup |
The nodes that follow it, e.g. a plate’s nodes over the beam’s profile. |
Returns
| Name | Type | Description |
|---|---|---|
class:xfea.model.ConstraintField |
The coupling’s field; the coupling is in the model’s constraints. |
Guidance (couplings)
- E.g. a beam’s end node and the plate nodes within the beam’s profile; a moment at the reference node turns them all.
- The coupled nodes must not carry supports of their own (
model.check()flags it). - As solids, a beam stub is a part of its own, tied to the plate instead (see contact).
add_rollerXY_bc(nodes, frame=None, **kwargs)
add_rollerXY_bc(nodes: Union[list[Node], NodesGroup], frame: Frame = None, **kwargs)
Hold nodes in z, free to slide in the xy plane; the rotations stay free (RollerBCXY).
Parameters
| Name | Type | Description |
|---|---|---|
| nodes | list[Node] | NodesGroup |
The nodes to hold; they must be in parts of this model. |
| frame | Frame, optional |
The frame whose local axes the support’s directions are along, or None for the global axes. |
Returns
| Name | Type | Description |
|---|---|---|
class:xfea.model.MechanicalBCField |
The support: the condition and its nodes. |
add_rollerXZ_bc(nodes, frame=None, **kwargs)
add_rollerXZ_bc(nodes: Union[list[Node], NodesGroup], frame: Frame = None, **kwargs)
Hold nodes in y, free to slide in the xz plane; the rotations stay free (RollerBCXZ).
Parameters
| Name | Type | Description |
|---|---|---|
| nodes | list[Node] | NodesGroup |
The nodes to hold; they must be in parts of this model. |
| frame | Frame, optional |
The frame whose local axes the support’s directions are along, or None for the global axes. |
Returns
| Name | Type | Description |
|---|---|---|
class:xfea.model.MechanicalBCField |
The support: the condition and its nodes. |
add_rollerX_bc(nodes, frame=None, **kwargs)
add_rollerX_bc(nodes: Union[list[Node], NodesGroup], frame: Frame = None, **kwargs)
Hold nodes in y and z, free to slide in x; the rotations stay free (RollerBCX).
Parameters
| Name | Type | Description |
|---|---|---|
| nodes | list[Node] | NodesGroup |
The nodes to hold; they must be in parts of this model. |
| frame | Frame, optional |
The frame whose local axes the support’s directions are along, or None for the global axes. |
Returns
| Name | Type | Description |
|---|---|---|
class:xfea.model.MechanicalBCField |
The support: the condition and its nodes. |
Guidance (supports)
- Each roller frees the translations in its name and holds the other translations; rotations stay
free.
add_rollerX_bc(alsoadd_rollerY_bc,add_rollerZ_bc) frees one,add_rollerXZ_bc(alsoadd_rollerXY_bc,add_rollerYZ_bc) frees two. For solids, a plane of symmetry normal to y isadd_rollerXZ_bc. - Beams and shells on a plane of symmetry also need the rotations in that plane held, which no
roller does. Normal to y:
model.add_bcs(MechanicalBCField(nodes, GeneralBC(y=True, xx=True, zz=True))).
add_rollerYZ_bc(nodes, frame=None, **kwargs)
add_rollerYZ_bc(nodes: Union[list[Node], NodesGroup], frame: Frame = None, **kwargs)
Hold nodes in x, free to slide in the yz plane; the rotations stay free (RollerBCYZ).
Parameters
| Name | Type | Description |
|---|---|---|
| nodes | list[Node] | NodesGroup |
The nodes to hold; they must be in parts of this model. |
| frame | Frame, optional |
The frame whose local axes the support’s directions are along, or None for the global axes. |
Returns
| Name | Type | Description |
|---|---|---|
class:xfea.model.MechanicalBCField |
The support: the condition and its nodes. |
add_rollerY_bc(nodes, frame=None, **kwargs)
add_rollerY_bc(nodes: Union[list[Node], NodesGroup], frame: Frame = None, **kwargs)
Hold nodes in x and z, free to slide in y; the rotations stay free (RollerBCY).
Parameters
| Name | Type | Description |
|---|---|---|
| nodes | list[Node] | NodesGroup |
The nodes to hold; they must be in parts of this model. |
| frame | Frame, optional |
The frame whose local axes the support’s directions are along, or None for the global axes. |
Returns
| Name | Type | Description |
|---|---|---|
class:xfea.model.MechanicalBCField |
The support: the condition and its nodes. |
add_rollerZ_bc(nodes, frame=None, **kwargs)
add_rollerZ_bc(nodes: Union[list[Node], NodesGroup], frame: Frame = None, **kwargs)
Hold nodes in x and y, free to slide in z; the rotations stay free (RollerBCZ).
Parameters
| Name | Type | Description |
|---|---|---|
| nodes | list[Node] | NodesGroup |
The nodes to hold; they must be in parts of this model. |
| frame | Frame, optional |
The frame whose local axes the support’s directions are along, or None for the global axes. |
Returns
| Name | Type | Description |
|---|---|---|
class:xfea.model.MechanicalBCField |
The support: the condition and its nodes. |
add_spring_links(first, second, stiffness, direction, only=None)→SpringLink
add_spring_links(
first,
second,
stiffness: float,
direction,
only: Optional[str] = None,
) -> SpringLink
Join pairs of nodes by springs, each first node to its second (SpringLink).
Parameters
| Name | Type | Description |
|---|---|---|
| first, second | list[Node] |
The springs’ two ends, as many first nodes as second. |
| stiffness | float | Each spring’s stiffness, force per length (N/mm for N and mm). |
| direction | sequence of 3 floats | The direction the springs act along (global). A spring is pulled when its second node moves away from its first along it. |
| only | {None, “tension”, “compression”}, optional | One-sided springs: "tension" resists only being pulled (a bolt, direction from its head to its nut), "compression" only being pushed. |
Returns
| Name | Type | Description |
|---|---|---|
class:xfea.model.SpringLink |
The springs, added to the model’s spring_links. |
add_spring_supports(nodes, stiffness, direction, only=None, **kwargs)
add_spring_supports(
nodes: Union[list[Node], NodesGroup],
stiffness: float,
direction,
only: Optional[str] = None,
**kwargs,
)
Put nodes on springs to the ground: a spring from a fixed point to each node (SpringSupport).
Parameters
| Name | Type | Description |
|---|---|---|
| nodes | list[Node] | NodesGroup |
The nodes on springs. |
| stiffness | float | Each node’s spring stiffness, force per length (N/mm for N and mm). |
| direction | sequence of 3 floats | The direction the springs act along (global). |
| only | {None, “tension”, “compression”}, optional | One-sided springs: "tension" resists only a node moving along direction (a bolt), "compression" only against it (bearing). |
Returns
| Name | Type | Description |
|---|---|---|
class:xfea.model.MechanicalBCField |
The springs: the condition and its nodes. |
Guidance (springs)
stiffnessis per node: to spread a stiffness over several nodes, divide it yourself.- A spring’s force is its node’s reaction: request
ReactionFieldResults()and readreact.get_result_at(node); a bolt in tension pulls its node towards the support. - A node on springs only needs holding in its other directions too (more springs, or a support).
- A spring on one node of a solid is a point load (a stress singularity): spread a bolt over the
nodes under its washer,
stiffness / len(nodes)each.
add_thermal_bc(nodes, temperature, **kwargs)→MechanicalBCField | List[MechanicalBCField]
add_thermal_bc(
nodes: Union[list[Node], NodesGroup],
temperature: float,
**kwargs,
) -> MechanicalBCField | List[MechanicalBCField]
Hold nodes at a temperature, for a heat transfer analysis (ImposedTemperature).
Parameters
| Name | Type | Description |
|---|---|---|
| nodes | list[Node] | NodesGroup |
The nodes held at the temperature. |
| temperature | float | The temperature, in the model’s temperature unit. |
Returns
| Name | Type | Description |
|---|---|---|
class:xfea.model.MechanicalBCField |
The field: the imposed temperature and its nodes. |
add_uniform_thermal_ics_field(T0, nodes)→InitialTemperatureField
add_uniform_thermal_ics_field(T0: float, nodes) -> InitialTemperatureField
Start nodes at one temperature, before the first step (an InitialTemperature).
Parameters
| Name | Type | Description |
|---|---|---|
| T0 | float | The initial temperature, in the model’s temperature unit. |
| nodes | list[Node] | NodesGroup |
The nodes that start at it. |
Returns
| Name | Type | Description |
|---|---|---|
class:xfea.model.InitialTemperatureField |
The field: the initial temperature and its nodes. |
array_parts(parts, n, transformation)→list[PartBase]
array_parts(
parts: list[PartBase],
n: int,
transformation: Transformation,
) -> list[PartBase]
Add to the model n copies of each part, the i-th copy moved by the transformation i times.
Parameters
| Name | Type | Description |
|---|---|---|
| parts | list[Part] |
The parts to copy. |
| n | int | The number of copies of each part. |
| transformation | Transformation |
The step from one copy to the next, such as a translation by the spacing. |
Returns
| Name | Type | Description |
|---|---|---|
| list[ | class:xfea.model.Part] |
The copies, added to the model. |
assign_keys(start=None, restart=False)
assign_keys(start: int | None = None, restart=False)
Number the model’s materials, sections, connectors, nodes and elements, the parts taken by name.
Parameters
| Name | Type | Description |
|---|---|---|
| start | int, optional | The first number, or None for the model’s own (1, as solvers number). |
| restart | bool, optional | True to number each part’s nodes and elements from start again; by default they are numbered on across the parts. |
check()→list
What a solver would get wrong without saying so: a list of ModelWarning.
Nodes that a tie’s tied side or a rigid coupling moves and that a
support also holds, then what the active solver plugin in particular
would get wrong (for instance I-section beams, which it solves as
rectangles). analyse() logs the findings
before every solve. An empty list means none found.
clear()
Remove the model’s parts, constraints, spring links, connectors, interfaces, problems and groups.
contains_material(material)→bool
contains_material(material: MaterialBase) -> bool
Whether a material is used by the model’s elements.
Parameters
| Name | Type | Description |
|---|---|---|
| material | MaterialBase |
The material to look for. |
Returns
| Name | Type | Description |
|---|---|---|
| bool |
contains_node(node)→Any
contains_node(node: Node) -> Any
Whether a node is in the part.
Parameters
| Name | Type | Description |
|---|---|---|
| node | Node |
The node to check. Returns —–– list of bool True if the node is in the part, False otherwise. |
contains_part(part)→bool
contains_part(part: PartBase) -> bool
Whether a part is in the model.
Parameters
| Name | Type | Description |
|---|---|---|
| part | Part |
The part to look for. |
Returns
| Name | Type | Description |
|---|---|---|
| bool |
contains_section(section)→bool
contains_section(section: SectionBase) -> bool
Whether a section is used by the model’s elements.
Parameters
| Name | Type | Description |
|---|---|---|
| section | SectionBase |
The section to look for. |
Returns
| Name | Type | Description |
|---|---|---|
| bool |
copy_part(part, transformation)→PartBase
copy_part(part: PartBase, transformation: Transformation) -> PartBase
Add to the model a copy of a part moved by a transformation.
Parameters
| Name | Type | Description |
|---|---|---|
| part | Part |
The part to copy. |
| transformation | Transformation |
The transformation that moves the copy. |
Returns
| Name | Type | Description |
|---|---|---|
class:xfea.model.Part |
The copy, added to the model. |
detect_interfaces(behavior, method='node_proximity', parts=None, part_pairs=None, tol=1.0, normal_tol=0.001, split=True, plane_split=False, add=True, **kwargs)→list[InterfaceBase]
detect_interfaces(
behavior: InteractionBase,
method: str = 'node_proximity',
parts: Optional[Iterable[PartBase]] = None,
part_pairs: Optional[Iterable[tuple[PartBase, PartBase]]] = None,
tol: float = 1.0,
normal_tol: float = 0.001,
split: bool = True,
plane_split: bool = False,
add: bool = True,
**kwargs,
) -> list[InterfaceBase]
Find where parts touch and make an interface there for each pair, with a contact or tie behaviour.
Parameters
| Name | Type | Description |
|---|---|---|
| behavior | InteractionBase | TieConstraint |
The behaviour of each interface found, such as HardContactNoFriction. |
| method | {“node_proximity”, “face_intersection”}, optional | How faces are matched: by coinciding nodes (the default), or by overlapping faces where the meshes differ. |
| parts | iterable[Part], optional |
The parts to pair up, every pair of them, or None for all the model’s parts. |
| part_pairs | iterable[tuple[Part, Part]], optional |
The (master, slave) pairs to look at, in place of parts. |
| tol | float, optional | The distance within which faces count as touching, in the model’s length unit; 1 by default. |
| normal_tol | float, optional | The tolerance on faces being parallel, for "face_intersection". |
| split | bool, optional | True (the default) for an interface per separate patch of contact, False for one per pair. |
| plane_split | bool, optional | True to keep faces on different planes in separate interfaces. |
| add | bool, optional | True (the default) to add the interfaces to the model, False only to return them. |
| **kwargs | Passed to each PartPartInterface, such as name. |
Returns
| Name | Type | Description |
|---|---|---|
| list[ | class:xfea.model.PartPartInterface] |
The interfaces found; their faces are named <master>_to_<slave>_master and ..._slave. |
Guidance (contact)
- In each pair the first part is the master (the support, the stiffer side), the second the
slave.
tolis the distance within which faces count as touching. - Contact carries compression only; with friction also along the faces. Without friction it holds nothing along the faces: a part held only by contact needs supports or springs there.
- The default method finds faces whose nodes coincide; where the meshes differ, pass
method="face_intersection". - Check what was found:
render_modellists every interface (its parts, how many faces). None listed means nothing was found: checktoland that the faces really touch. - Through the conversion service: contact with and without friction, and ties. Not yet: thermal interfaces, connectors.
find_closest_nodes_to_node(node, number_of_nodes=1, plane=None)→Any
find_closest_nodes_to_node(
node: Node,
number_of_nodes: int = 1,
plane: Optional[Plane] = None,
) -> Any
The part’s nodes closest to a given node, the node itself left out.
Parameters
| Name | Type | Description |
|---|---|---|
| node | Node |
The node to search around. |
| number_of_nodes | int, optional | How many nodes to find. Default 1. |
| report | bool, optional | Return each node with its distance, as a dict. Default False. |
| single | bool, optional | Return the closest node itself, not a group. Default False. Returns —–– list of NodesGroup | dict[Node, float] | Node | None The closest nodes, nearest first; {node: distance} with report; the closest node with single; None if none is found. |
find_closest_nodes_to_point(point, number_of_nodes=1, plane=None)→Any
find_closest_nodes_to_point(
point: Point,
number_of_nodes: int = 1,
plane: Optional[Plane] = None,
) -> Any
The part’s nodes closest to a point.
Parameters
| Name | Type | Description |
|---|---|---|
| point | Point | list[float] |
The point, or its x, y, z coordinates. |
| number_of_nodes | int, optional | How many nodes to find, capped to the part’s nodes. Default 1. |
| report | bool, optional | Return each node with its distance, as a dict. Default False. |
| single | bool, optional | With number_of_nodes=1, return the node itself, not a group. Default False. Returns —–– list of NodesGroup | dict[Node, float] | Node | None The closest nodes; {node: distance} with report; the node with single; None if number_of_nodes is 0. |
find_element_by_key(key)→Any
find_element_by_key(key: int) -> Any
The part’s element with a given key, or None.
Parameters
| Name | Type | Description |
|---|---|---|
| key | int | The element’s key. Returns —–– list of ElementBase | None The element, or None if not found. |
find_element_by_name(name)→Any
find_element_by_name(name: str) -> Any
The part’s first element with a given name, or None.
Parameters
| Name | Type | Description |
|---|---|---|
| name | str | The name to look for. Returns —–– list of ElementBase | None The element, or None if not found. |
find_faces_in_polygon(key)→Any
find_faces_in_polygon(key: int) -> Any
The faces of the part’s shell and solid elements inside a planar polygon.
Parameters
| Name | Type | Description |
|---|---|---|
| polygon | Polygon |
The polygon for the search. |
| tol | float, optional | A scale factor on the polygon about its centre, not a distance. Default 1.1 (10% larger). Returns —–– list of FacesGroup The faces whose nodes are all on the polygon’s plane and inside its outline. |
find_material_by_key(key)→Optional[MaterialBase]
find_material_by_key(key: int) -> Optional[MaterialBase]
The material of the model’s elements with a given key (number), or None if there is none.
Parameters
| Name | Type | Description |
|---|---|---|
| key | int | The key of the material, as assign_keys() numbers it. |
Returns
| Name | Type | Description |
|---|---|---|
class:xfea.model.MaterialBase | None |
find_material_by_name(name)→Optional[MaterialBase]
find_material_by_name(name: str) -> Optional[MaterialBase]
The material of the model’s elements with a given name, or None if there is none.
Parameters
| Name | Type | Description |
|---|---|---|
| name | str | The name of the material. |
Returns
| Name | Type | Description |
|---|---|---|
class:xfea.model.MaterialBase | None |
find_materials_by_attribute(attr, value, tolerance=1)→list[MaterialBase]
find_materials_by_attribute(
attr: str,
value: Union[str, int, float],
tolerance: float = 1,
) -> list[MaterialBase]
The materials of the model’s elements whose numeric attribute is within a tolerance of a value.
Parameters
| Name | Type | Description |
|---|---|---|
| attr | str | The name of the attribute, such as "E". |
| value | int | float | The value to match. |
| tolerance | float, optional | The largest difference that still matches, 1 by default (strictly less). |
Returns
| Name | Type | Description |
|---|---|---|
| list[ | class:xfea.model.MaterialBase] |
find_node_by_key(key)→Any
find_node_by_key(key: int) -> Any
The part’s node with a given key, or None.
Parameters
| Name | Type | Description |
|---|---|---|
| key | int | The node’s key. Returns —–– list of Node | None The node, or None if not found. |
find_node_by_name(name)→Any
find_node_by_name(name: str) -> Any
The part’s nodes with a given name.
Parameters
| Name | Type | Description |
|---|---|---|
| name | str | The name to look for. Returns —–– list of set[Node] The nodes with that name; empty if none. |
find_nodes_in_polygon(polygon, tol=1.1)→Any
find_nodes_in_polygon(polygon: Polygon, tol: float = 1.1) -> Any
The part’s nodes inside a planar polygon: on its plane and within its outline.
Parameters
| Name | Type | Description |
|---|---|---|
| polygon | Polygon |
The polygon for the search. |
| tol | float, optional | A scale factor on the polygon about its centre, not a distance. Default 1.1 (10% larger). Returns —–– list of NodesGroup The nodes inside the polygon. |
find_nodes_on_plane(plane, tol=1)→Any
find_nodes_on_plane(plane: Plane, tol: float = 1) -> Any
The part’s nodes on a plane, within a distance of it.
Parameters
| Name | Type | Description |
|---|---|---|
| plane | Plane |
The plane. |
| tol | float, optional | The largest distance from the plane, a length (mm for mm). Default 1.0. Returns —–– list of NodesGroup The nodes on the plane. |
find_part_by_name(name, casefold=False)→Optional[PartBase]
find_part_by_name(name: str, casefold: bool = False) -> Optional[PartBase]
The part of the model with a given name, or None if there is none.
Parameters
| Name | Type | Description |
|---|---|---|
| name | str | The name to match; spaces in it are read as underscores, as in part names. |
| casefold | bool, optional | True for a case-insensitive match; by default the case must match. |
Returns
| Name | Type | Description |
|---|---|---|
class:xfea.model.Part | None |
The part, or None. |
find_section_by_key(key)→Optional[SectionBase]
find_section_by_key(key: int) -> Optional[SectionBase]
The section of the model’s elements with a given key (number), or None if there is none.
Parameters
| Name | Type | Description |
|---|---|---|
| key | int | The key of the section, as assign_keys() numbers it. |
Returns
| Name | Type | Description |
|---|---|---|
class:xfea.model.SectionBase | None |
find_section_by_name(name)→Optional[SectionBase]
find_section_by_name(name: str) -> Optional[SectionBase]
The section of the model’s elements with a given name, or None if there is none.
Parameters
| Name | Type | Description |
|---|---|---|
| name | str | The name of the section. |
Returns
| Name | Type | Description |
|---|---|---|
class:xfea.model.SectionBase | None |
find_sections_by_attribute(attr, value, tolerance=1)→list[SectionBase]
find_sections_by_attribute(
attr: str,
value: Union[str, int, float],
tolerance: float = 1,
) -> list[SectionBase]
The sections of the model’s elements whose numeric attribute is within a tolerance of a value.
Parameters
| Name | Type | Description |
|---|---|---|
| attr | str | The name of the attribute, such as "A". |
| value | int | float | The value to match. |
| tolerance | float, optional | The largest difference that still matches, 1 by default (strictly less). |
Returns
| Name | Type | Description |
|---|---|---|
| list[ | class:xfea.model.SectionBase] |
group_parts_where(attr, value)→PartsGroup
group_parts_where(attr: str, value: Union[str, int, float]) -> PartsGroup
Register to the model a group of the parts whose attribute equals a value.
Parameters
| Name | Type | Description |
|---|---|---|
| attr | str | The name of the attribute. |
| value | str | int | float | The value it must equal. |
Returns
| Name | Type | Description |
|---|---|---|
class:xfea.model.PartsGroup |
The new group. |
remove_bcs(field)
remove_bcs(field: MechanicalBCField)
Remove a support from the model, freeing its nodes.
Parameters
| Name | Type | Description |
|---|---|---|
| field | MechanicalBCField |
The support, as an add_*_bc method returned it. |
remove_nodes_from_bcs(nodes, field)
remove_nodes_from_bcs(nodes: Union[list[Node], NodesGroup], field: MechanicalBCField)
Free some nodes of a support; the support keeps holding the others.
Parameters
| Name | Type | Description |
|---|---|---|
| nodes | list[Node] | NodesGroup |
The nodes to free. |
| field | MechanicalBCField |
The support, as an add_*_bc method returned it. |
reset()
Clear the model (clear()), forget its path and numbering, and take the "SI_mm" constants.
summary()→str
A text summary of the model: its parts (nodes, elements, materials, sections), supports and problems.
Returns
| Name | Type | Description |
|---|---|---|
| str | The summary. |
summary_data()→dict
A JSON-serializable dict describing the model: its parts and mesh, materials, sections, interfaces and problems.
The dict is written alongside the pickle, as model.json for model.pkl, by
to_pickle(). It provides a human-readable record of what
the model contains — mesh stats, materials, problem parameters —
without needing to load Python.
© 2026 Francesco Ranaudo · Text and pictures CC BY 4.0 · Code Elastic License 2.0 · how to reuse them