Skip to content

embedded_beam_solid_interface

embedded_beam_solid_interface

Attributes

model module-attribute

model = Model()

soil_mat module-attribute

soil_mat = elastic_isotropic(user_name='Soil', E=30000000.0, nu=0.3, rho=2000)

brick_ele module-attribute

brick_ele = std(ndof=3, material=soil_mat)

beam_sec module-attribute

beam_sec = elastic(user_name='PileSection', E=200000000000.0, A=0.05, Iz=0.0001, Iy=0.0001)

transf module-attribute

transf = transformation3d('Linear', 0, 1, 0)

beam_ele module-attribute

beam_ele = disp(ndof=6, section=beam_sec, transformation=transf)

dx module-attribute

dx = 0.5

Nx module-attribute

Nx = int((10 - -10) / dx)

Ny module-attribute

Ny = Nx

Nz module-attribute

Nz = int((0 - -20) / dx)

piles module-attribute

piles = structured_lines(user_name='piles', element=beam_ele, base_point_x=-4, base_point_y=-4, base_point_z=-8, base_vector_1_x=1, base_vector_1_y=0, base_vector_1_z=0, base_vector_2_x=0, base_vector_2_y=1, base_vector_2_z=0, normal_x=0, normal_y=0, normal_z=1, grid_size_1=8, grid_size_2=8, spacing_1=1.0, spacing_2=1.0, number_of_lines=10, length=10, offset_1=0, offset_2=0)

interface_radius module-attribute

interface_radius = 0.25

Classes

InterfaceBase

InterfaceBase(name: str, owners: List[str])

Bases: ABC

Common logic for all interface objects on one Model model.

HandlesDecompositionMixin

Role mixin for components that react to decomposition or core updates.

Use this mixin when a component depends on partition/core ownership data and must update itself after the assembled mesh has been repartitioned or after core-conflict resolution has changed that ownership information.

This is a narrower and more advanced role than ordinary assembly hooks. It matters when a component caches partition-sensitive state or needs to keep parallel/decomposition metadata aligned with the latest assembled mesh.

Example
class PartitionAwareInterface(HandlesDecompositionMixin):
    def on_partition_update(self, assembled_mesh, **kwargs):
        self.cached_core_ids = assembled_mesh.cell_data["Core"]
Tip

Use this mixin only when the component genuinely depends on partition-aware state. Many advanced interfaces need POST_ASSEMBLE hooks but do not need decomposition updates.

Methods:
on_partition_update
on_partition_update(assembled_mesh, **kwargs) -> None

Refresh component state after partition/core ownership changes.

Subclasses implement this hook when the component stores data that must stay aligned with the current decomposition of the assembled mesh.

Parameters:

Name Type Description Default
assembled_mesh

The global assembled mesh containing the updated core and partition information.

required
**kwargs

Arbitrary keyword arguments passed from the update context.

{}

MeshPart

MeshPart(category: str, mesh_type: str, user_name: str, element: Optional[Element], region: Optional[RegionBase] = None)

Bases: ABC

Base class for mesh parts on one Model model.

Instances do not self-register. A :class:MeshPartManager owns tag assignment and lifecycle.

SingleLineMesh

SingleLineMesh(user_name: str, element: Element, region: Optional[RegionBase] = None, *, x0: float = 0.0, y0: float = 0.0, z0: float = 0.0, x1: float = 1.0, y1: float = 0.0, z1: float = 0.0, number_of_lines: int = 1, merge_points: bool = True, density: Optional[float] = None, mass_per_length: Optional[float] = None)

Bases: LineMeshPart

Parametric 1D line mesh part defined between two points in 3D space.

This mesh part discretizes a straight line between a start point (x0, y0, z0) and an end point (x1, y1, z1) into a specified number of segments, automatically assigning physical beam element templates and computing consistent lumped point Mass data.

Note
  • Requires a compatible beam element that has a valid cross-section and coordinate transformation.
  • Total element mass and rotational inertia are lumped and assigned to generated point arrays.
Example
from femora.core.model import Model

model = Model()
sec = model.section.beam.elastic(
    user_name="column_sec", E=29000.0, A=10.0, Iz=100.0, Iy=100.0
)
transf = model.transformation.transformation3d("Linear", 0.0, 1.0, 0.0)
beam_ele = model.element.beam.disp(ndof=6, section=sec, transformation=transf)

# Discretize a single vertical column
column = model.meshpart.line.single_line(
    user_name="pier_column",
    element=beam_ele,
    x0=0.0, y0=0.0, z0=0.0,
    x1=0.0, y1=0.0, z1=15.0,
    number_of_lines=5,
)
print(column.tag)

Create a parametric single line mesh part.

Parameters:

Name Type Description Default
user_name str

Unique user-defined name for this mesh part.

required
element Element

Associated Element template used for discretization.

required
region Optional[RegionBase]

Physical Region where this mesh part is added.

None
x0 float

Start point X-coordinate.

0.0
y0 float

Start point Y-coordinate.

0.0
z0 float

Start point Z-coordinate.

0.0
x1 float

End point X-coordinate.

1.0
y1 float

End point Y-coordinate.

0.0
z1 float

End point Z-coordinate.

0.0
number_of_lines int

Number of element segments along the line.

1
merge_points bool

If True, duplicate nodes at segment boundaries are merged.

True
density Optional[float]

Material density used by this meshpart to create nodal translational and rotational Mass arrays from the element section properties.

None
mass_per_length Optional[float]

Compatibility alias for older line-mass workflows. Femora converts it to density using section area; prefer density for new code.

None

Raises:

Type Description
ValueError

If element is not compatible, start and end points are identical, or number_of_lines is less than 1.

TypeError

If merge_points is not a boolean.

Methods:
is_element_compatible
is_element_compatible(element: Element) -> bool

Verify that the element belongs to compatible type families and has cross-section and transformation metadata.

Parameters:

Name Type Description Default
element Element

Element template to verify.

required

Returns:

Name Type Description
bool bool

True if compatible, False otherwise.

generate_mesh
generate_mesh() -> pv.PolyData

Generate line coordinate points, connectivity indices, and point Mass data.

Returns:

Type Description
PolyData

pv.UnstructuredGrid: The generated UnstructuredGrid mesh with point Mass data.

StructuredLineMesh

StructuredLineMesh(user_name: str, element: Element, region: Optional[RegionBase] = None, *, base_point_x: float = 0.0, base_point_y: float = 0.0, base_point_z: float = 0.0, base_vector_1_x: float = 1.0, base_vector_1_y: float = 0.0, base_vector_1_z: float = 0.0, base_vector_2_x: float = 0.0, base_vector_2_y: float = 1.0, base_vector_2_z: float = 0.0, normal_x: float = 0.0, normal_y: float = 0.0, normal_z: float = 1.0, grid_size_1: int = 10, grid_size_2: int = 10, spacing_1: float = 1.0, spacing_2: float = 1.0, length: float = 1.0, offset_1: float = 0.0, offset_2: float = 0.0, number_of_lines: int = 1, merge_points: bool = True, density: Optional[float] = None, mass_per_length: Optional[float] = None)

Bases: LineMeshPart

Parametric structured grid of 1D line elements generated along a plane normal.

This mesh part generates a grid of parallel line elements (beams or columns) oriented along a specified vector normal. It is highly useful for structural sub-assemblies such as pile group configurations or multi-column bridge piers, automatically compiling connectivity and calculating mass distributions.

Note
  • Requires a compatible beam element that possesses both a defined cross-section and a coordinate transformation.
  • Rotational and translational masses are integrated per unit length and lumped onto point Mass arrays.
Example
from femora.core.model import Model

model = Model()
sec = model.section.beam.elastic(
    user_name="beam_sec", E=29000.0, A=10.0, Iz=100.0, Iy=100.0
)
transf = model.transformation.transformation3d("Linear", 0.0, 1.0, 0.0)
beam_ele = model.element.beam.disp(ndof=6, section=sec, transformation=transf)

# Create a 2x2 pile group of vertical structured lines
piles = model.meshpart.line.structured_lines(
    user_name="pile_group",
    element=beam_ele,
    grid_size_1=1,
    grid_size_2=1,
    spacing_1=5.0,
    spacing_2=5.0,
    length=20.0,
    normal_x=0.0,
    normal_y=0.0,
    normal_z=1.0,
)
print(piles.tag)

Create a parametric structured grid of line elements.

Parameters:

Name Type Description Default
user_name str

Unique user-defined name for this mesh part.

required
element Element

Associated Element template used for discretization.

required
region Optional[RegionBase]

Physical Region where this mesh part is added.

None
base_point_x float

X-coordinate of the grid base point.

0.0
base_point_y float

Y-coordinate of the grid base point.

0.0
base_point_z float

Z-coordinate of the grid base point.

0.0
base_vector_1_x float

X-component of the first grid vector direction.

1.0
base_vector_1_y float

Y-component of the first grid vector direction.

0.0
base_vector_1_z float

Z-component of the first grid vector direction.

0.0
base_vector_2_x float

X-component of the second grid vector direction.

0.0
base_vector_2_y float

Y-component of the second grid vector direction.

1.0
base_vector_2_z float

Z-component of the second grid vector direction.

0.0
normal_x float

X-component of the line direction vector (plane normal).

0.0
normal_y float

Y-component of the line direction vector (plane normal).

0.0
normal_z float

Z-component of the line direction vector (plane normal).

1.0
grid_size_1 int

Number of cell intervals along the first grid direction.

10
grid_size_2 int

Number of cell intervals along the second grid direction.

10
spacing_1 float

Distance between grid lines along the first direction.

1.0
spacing_2 float

Distance between grid lines along the second direction.

1.0
length float

Length of each line element.

1.0
offset_1 float

Position offset along the first direction.

0.0
offset_2 float

Position offset along the second direction.

0.0
number_of_lines int

Number of element segments to divide each line.

1
merge_points bool

If True, duplicate nodes at adjacent segment boundaries are merged.

True
density Optional[float]

Material density used by this meshpart to create nodal translational and rotational Mass arrays from the element section properties.

None
mass_per_length Optional[float]

Compatibility alias for older line-mass workflows. Femora converts it to density using section area; prefer density for new code.

None

Raises:

Type Description
ValueError

If element is not compatible, grid sizes are negative, spacing or length are non-positive, or number_of_lines is less than 1.

TypeError

If merge_points is not a boolean.

Methods:
is_element_compatible
is_element_compatible(element: Element) -> bool

Verify that the element belongs to compatible type families and has cross-section and transformation metadata.

Parameters:

Name Type Description Default
element Element

Element template to verify.

required

Returns:

Name Type Description
bool bool

True if compatible, False otherwise.

generate_mesh
generate_mesh() -> pv.UnstructuredGrid

Generate lines grid coordinates, compile connectivity, and compute lumped point Mass arrays.

Returns:

Type Description
UnstructuredGrid

pv.UnstructuredGrid: The generated UnstructuredGrid mesh with Point Mass data.

FemoraEvent

Bases: Enum

Lifecycle signals emitted by Femora runtime subsystems.

These enum values describe when a callback is being invoked. They are not ordinary modeling commands. Instead, they mark important stages in the runtime lifecycle so advanced components can react at the right time.

The most important practical events are:

  • PRE_ASSEMBLE: emitted before the final assembled mesh is built
  • POST_ASSEMBLE: emitted after the final assembled mesh exists
  • RESOLVE_CORE_CONFLICTS: emitted after assembly when partition/core ownership updates may need follow-up work
  • PRE_EXPORT and POST_EXPORT: emitted around export-time workflows

More specialized events such as EMBEDDED_BEAM_SOLID_TCL are used by advanced exporters and interface-specific integrations.

EmbeddedInfo dataclass

EmbeddedInfo(beams: Union[List[int], Set[int]], core_number: int, beams_solids: List[Tuple[List[int], List[int]]])

Optimized EmbeddedInfo data structure for fast interface comparisons.

This structure tracks connection mapping between embedded beam elements and surrounding solid elements, deduplicating equivalent layouts and detecting core partition conflicts.

Create an EmbeddedInfo instance.

Parameters:

Name Type Description Default
beams Union[List[int], Set[int]]

A set or list of integers representing beam element identifiers.

required
core_number int

An integer core partition ID.

required
beams_solids List[Tuple[List[int], List[int]]]

List of (list1, list2) mapping tuples, where list1 is the beam connectivity list and list2 is the solid element ID list.

required
Attributes
solids_set property
solids_set: FrozenSet[int]

Get the set of solid elements associated with this interface.

beams_solids property
beams_solids: List[Tuple[List[int], List[int]]]

Get beams_solids in list format for compatibility.

Methods:
__eq__
__eq__(other: object) -> bool

Check if two EmbeddedInfo objects are logically equal in O(1) time.

is_conflict
is_conflict(other: EmbeddedInfo) -> bool

Check if two objects conflict (have the same beams and overlap on list1 connectivities).

Parameters:

Name Type Description Default
other EmbeddedInfo

The other EmbeddedInfo instance to compare.

required

Returns:

Type Description
bool

True if there is a mapping conflict, False otherwise.

is_similar
is_similar(other: EmbeddedInfo) -> bool

Check if two objects are similar (share identical beams or solids without conflict).

Parameters:

Name Type Description Default
other EmbeddedInfo

The other EmbeddedInfo instance to compare.

required

Returns:

Type Description
bool

True if similar, False otherwise.

__hash__
__hash__() -> int

Compute the hash using pre-computed canonical values.

compare
compare(other: EmbeddedInfo) -> str

Compare with another EmbeddedInfo and return the relationship type.

Parameters:

Name Type Description Default
other EmbeddedInfo

The other EmbeddedInfo to compare.

required

Returns:

Type Description
str

A string indicating the relationship: "equal", "conflict",

str

"similar", or "unrelated".

Raises:

Type Description
TypeError

If other is not an instance of EmbeddedInfo.

with_core_number
with_core_number(new_core_number: int) -> EmbeddedInfo

Return a copy of this EmbeddedInfo with a different core_number.

Parameters:

Name Type Description Default
new_core_number int

The core partition number for the copy.

required

Returns:

Type Description
EmbeddedInfo

A new EmbeddedInfo instance with the updated core partition.

RegionBase

RegionBase(user_name: str = None, damping: Damping = None)

Bases: ABC

Abstract base class for defining regions in a structural model.

Region objects do not self-register and do not assign their own tags. A RegionManager owns lifecycle operations, tag assignment, removal, and retagging for a local model context.

_SolidSearchContext dataclass

_SolidSearchContext(cell_ids: ndarray, centers: ndarray, search_radii: ndarray, tree: cKDTree)

Cached solid-cell geometry for beam-solid neighborhood search.

EmbeddedBeamSolidInterface

EmbeddedBeamSolidInterface(name: str, beam_part: 'MeshPart | str | int', solid_parts: 'List[MeshPart | str | int] | None' = None, shape: str = 'circle', radius: float = 0.5, radius_y: float | None = None, radius_z: float | None = None, width: float | None = None, height: float | None = None, section_points: Sequence[Sequence[float]] | None = None, n_peri: int = 8, n_long: int = 10, penalty_param: float = 1000000000000.0, g_penalty: bool = True, scale_start: float = 1.0, scale_end: float = 1.0, selection_margin: float = 0.35, _diagnostic_geometry: bool = False, _diagnostic_line_mesh: bool = False, region: 'RegionBase | None' = None, write_connectivity: bool = False, write_interface: bool = False, *, meshpart)

Bases: InterfaceBase, HandlesDecompositionMixin

Embedded beam-solid contact interface.

EmbeddedBeamSolidInterface models the kinematic and force contact interaction between line elements (e.g. beam-column piles) and 3D solid elements (e.g. soil). It enforces matching partition cores between the embedded beam elements and overlapping solid elements.

Tcl form

None (renders internally via OpenSees interface-specific TCL commands).

Example
from femora.core.model import Model

model = Model()
# Create an interface for a piles meshpart within the soil domain
interface = model.interface.beam_solid_interface(
    name="pile_soil_interface",
    beam_part="piles",
    radius=0.25,
    n_peri=8,
    n_long=5,
    penalty_param=1.0e12,
    g_penalty=True,
)

Create an EmbeddedBeamSolidInterface.

Parameters:

Name Type Description Default
name str

Unique name of the contact interface.

required
beam_part 'MeshPart | str | int'

The beam part instance, name, or tag.

required
solid_parts 'List[MeshPart | str | int] | None'

Optional list of solid part instances, names, or tags.

None
shape str

Shape profile of the beam cross-section. Production OpenSees export currently supports only "circle". Defaults to "circle".

'circle'
radius float

Radius of the circular beam interface geometry. Defaults to 0.5.

0.5
radius_y float | None

Internal diagnostic ellipse semi-axis in the local section y direction.

None
radius_z float | None

Internal diagnostic ellipse semi-axis in the local section z direction.

None
width float | None

Internal diagnostic rectangle width in the local section y direction.

None
height float | None

Internal diagnostic rectangle height in the local section z direction.

None
section_points Sequence[Sequence[float]] | None

Internal diagnostic polygon vertices as local (y, z) pairs.

None
n_peri int

Number of points along the perimeter of the circular section. Defaults to 8.

8
n_long int

Number of points along the longitudinal axis of the beam. Defaults to 10.

10
penalty_param float

Penalty stiffness parameter for the constraint. Defaults to 1.0e12.

1000000000000.0
g_penalty bool

If True, uses the geometric penalty formulation. Defaults to True.

True
scale_start float

Internal diagnostic interface envelope scale at the first endpoint of the beam path. Production export requires 1.0.

1.0
scale_end float

Internal diagnostic interface envelope scale at the second endpoint of the beam path. Production export requires 1.0.

1.0
selection_margin float

Fraction of each candidate solid cell bounding radius allowed outside the interface envelope during fast solid discovery. Smaller values select tighter neighborhoods. Defaults to 0.35.

0.35
_diagnostic_geometry bool

Internal flag used by visual diagnostics to exercise non-exported envelope shapes and tapered discovery.

False
_diagnostic_line_mesh bool

Internal flag used by visual diagnostics to allow generic line-cell meshparts that are not export-ready.

False
region 'RegionBase | None'

Optional region bounding the interface. Not implemented yet.

None
write_connectivity bool

If True, outputs boundary connectivity maps to file. Defaults to False.

False
write_interface bool

If True, outputs boundary mesh surfaces to file. Defaults to False.

False
meshpart

MeshPart registry manager from the parent model.

required

Raises:

Type Description
ValueError

If beam_part cannot be resolved or if shape is unsupported.

TypeError

If argument types are invalid (e.g. beam_part is not a line mesh).

NotImplementedError

If unsupported parameter configurations are provided.

Methods:
plot
plot(*, show_mesh: bool = True, show_envelope: bool = True, show_edges: bool = True, mesh_opacity: float = 0.08, selected_opacity: float = 0.65, envelope_opacity: float = 0.35, beam_color: str = 'black', selected_color: str = 'orange', envelope_color: str = 'steelblue', off_screen: bool = False, screenshot: str | None = None, window_size: tuple[int, int] = (1400, 900), return_plotter: bool = False) -> pv.Plotter | None

Plot the assembled beam-solid interface selection.

The plot shows the assembled model as a faint reference mesh, the beam cells owned by this interface, the selected surrounding solid cells, and the circular radius envelope used by Femora-side discovery.

Parameters:

Name Type Description Default
show_mesh bool

If True, draw the whole assembled mesh as a faint wireframe.

True
show_envelope bool

If True, draw the radius envelope around each beam segment.

True
show_edges bool

If True, draw edges on selected solid cells.

True
mesh_opacity float

Opacity of the assembled reference mesh.

0.08
selected_opacity float

Opacity of selected solid cells.

0.65
envelope_opacity float

Opacity of the radius envelope.

0.35
beam_color str

Color used for beam cells.

'black'
selected_color str

Color used for selected solid cells.

'orange'
envelope_color str

Color used for the radius envelope.

'steelblue'
off_screen bool

If True, render without opening an interactive window.

False
screenshot str | None

Optional image path to write a screenshot.

None
window_size tuple[int, int]

PyVista window size in pixels.

(1400, 900)
return_plotter bool

If True, return the configured plotter instead of calling show().

False

Returns:

Type Description
Plotter | None

A PyVista plotter when return_plotter is True; otherwise None.

Raises:

Type Description
RuntimeError

If the interface is unmanaged, the model is not assembled, or no embedded interface data has been collected yet.

Model

Model(**kwargs)

Root runtime object for Femora model construction, assembly, and export.

Initialize a Femora Model instance.

Parameters:

Name Type Description Default
**kwargs

Keyword arguments including: - model_name (str): Name of the model - model_path (str): Path to save the model

{}
Methods:
set_nodetag_start
set_nodetag_start(start_tag: int) -> None

Set the starting tag number for nodes in exported TCL.

Parameters:

Name Type Description Default
start_tag int

First node tag to use (must be >= 1)

required
set_eletag_start
set_eletag_start(start_tag: int) -> None

Set the starting tag number for elements in exported TCL.

Parameters:

Name Type Description Default
start_tag int

First element tag to use (must be >= 1)

required
set_start_core_tag
set_start_core_tag(start_tag: int) -> None

Set the starting tag number for cores in exported TCL.

Parameters:

Name Type Description Default
start_tag int

First core tag to use (must be >= 0)

required
export_to_tcl
export_to_tcl(filename=None, progress_callback=None, decimals=5)

Export the model to a TCL file

Parameters:

Name Type Description Default
filename str

The filename to export to. If None, uses model_name in model_path

None
progress_callback callable

Callback function to report progress. If None, uses tqdm progress bar.

None

Returns:

Name Type Description
bool

True if export was successful, False otherwise

Raises:

Type Description
ValueError

If no filename is provided and model_name/model_path are not set

export_to_vtk
export_to_vtk(filename=None, write_info_json=False, indent=2)

Export the model to a vtk file

Parameters:

Name Type Description Default
filename str

The filename to export to. If None, uses model_name in model_path

None
write_info_json bool

When True, also write a lightweight sidecar JSON file.

False
indent int

JSON indentation level for sidecar info.

2

Returns:

Name Type Description
bool

True if export was successful, False otherwise

export_to_json
export_to_json(filename=None, indent=2)

Export a lightweight structural snapshot of the model to JSON.

Parameters:

Name Type Description Default
filename str

The filename to export to. If None, uses model_name in model_path

None
indent int

JSON indentation level. Defaults to 2.

2

Returns:

Name Type Description
bool

True if export was successful

set_model_info
set_model_info(model_name=None, model_path=None)

Update model information

Parameters:

Name Type Description Default
model_name str

New model name

None
model_path str

New model path

None
set_results_folder
set_results_folder(folder_name)

Set the results folder for the model This method updates the results folder where simulation results will be stored.

Parameters:

Name Type Description Default
folder_name str

path to the results folder

required
get_results_folder
get_results_folder()

Get the current results folder path

Returns:

Name Type Description
str

The path to the results folder

get_femora_parts
get_femora_parts() -> list[dict]

Return a read-only snapshot of source parts registered for VTK export.

print_info
print_info()

Print information about the current model on the console

Returns:

Type Description

None

get_max_ele_tag
get_max_ele_tag()

Get the maximum element tag in the assembled mesh

Returns:

Type Description

positive int: maximum element tag

-1: if no mesh is assembled

get_max_node_tag
get_max_node_tag()

Get the maximum node tag in the assembled mesh

Returns:

Type Description

positive int: maximum node tag

-1: if no mesh is assembled

get_start_ele_tag
get_start_ele_tag()

Get the start element tag

Returns:

Name Type Description
int

start element tag

get_start_node_tag
get_start_node_tag()

Get the start node tag

Returns:

Name Type Description
int

start node tag

clear_model
clear_model()

Clear the current model and reset all components to their initial state. This method wipes the current mesh, materials, elements, constraints, and all other components, allowing you to start fresh without needing to create a new Model instance.