Skip to content

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 with method="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. zones keep 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 (also add_rollerY_bc, add_rollerZ_bc) frees one, add_rollerXZ_bc (also add_rollerXY_bc, add_rollerYZ_bc) frees two. For solids, a plane of symmetry normal to y is add_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)

  • stiffness is per node: to spread a stiffness over several nodes, divide it yourself.
  • A spring’s force is its node’s reaction: request ReactionFieldResults() and read react.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. tol is 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_model lists every interface (its parts, how many faces). None listed means nothing was found: check tol and 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