embedded_beam_solid_interface
embedded_beam_solid_interface
Attributes
soil_mat
module-attribute
beam_sec
module-attribute
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)
Classes
InterfaceBase
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
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
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
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. |
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
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. |
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 builtPOST_ASSEMBLE: emitted after the final assembled mesh existsRESOLVE_CORE_CONFLICTS: emitted after assembly when partition/core ownership updates may need follow-up workPRE_EXPORTandPOST_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
Get the set of solid elements associated with this interface.
beams_solids
property
Get beams_solids in list format for compatibility.
Methods:
__eq__
Check if two EmbeddedInfo objects are logically equal in O(1) time.
is_conflict
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
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. |
compare
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
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
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
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
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 |
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 |
TypeError
|
If argument types are invalid (e.g. |
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 |
False
|
Returns:
| Type | Description |
|---|---|
Plotter | None
|
A PyVista plotter when |
Raises:
| Type | Description |
|---|---|
RuntimeError
|
If the interface is unmanaged, the model is not assembled, or no embedded interface data has been collected yet. |
Model
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 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 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 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 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 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 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
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 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 the current results folder path
Returns:
| Name | Type | Description |
|---|---|---|
str |
The path to the results folder |
get_femora_parts
Return a read-only snapshot of source parts registered for VTK export.
print_info
Print information about the current model on the console
Returns:
| Type | Description |
|---|---|
|
None |
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 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 the start element tag
Returns:
| Name | Type | Description |
|---|---|---|
int |
start element tag |
get_start_node_tag
Get the start node tag
Returns:
| Name | Type | Description |
|---|---|---|
int |
start node tag |