FEA Guide

Overview

OpenBrIM's FEA (Finite Element Analysis) system provides comprehensive structural analysis capabilities for bridge engineering. The FEA module integrates seamlessly with the parametric engine (ParamML), allowing AI agents to create complex analysis models using XML-based object definitions.

This guide explains the FEA objects, analysis types, and patterns for AI agents who will create finite element models and perform structural analysis.

Key Capabilities:

Analysis Types: Static linear, eigenvalue/modal, response spectrum, pushover, staged construction
Element Library: Beam, truss, shell, spring elements
Advanced Features: Automatic meshing, live load analysis, prestressing, time-dependent effects
Integration: Full parametric control via ParamML expressions

Core Concepts

1. FEA Object Hierarchy

All FEA objects follow the OpenBrIM object model:

Objects have unique IDs, Names (N), and Types (T)
Properties are defined as parameters (P elements)
Objects reference each other by name using the @ObjectName|ObjectType syntax

2. Coordinate Systems

Nodes can be positioned using different coordinate systems:

Global Coordinates (X, Y, Z): Project-wide XYZ coordinates
Alignment-Based Coordinates (XLocal, YLocal, ZLocal): Coordinates relative to a bridge alignment/station
Node Local Coordinate System: Each node can have its own local coordinate system for custom orientation

3. Degrees of Freedom (DOF)

Each node has 6 DOF:

Translations: Tx (index 0), Ty (index 1), Tz (index 2)
Rotations: Rx (index 3), Ry (index 4), Rz (index 5)

These indices are used in properties like Dir in pushover analysis.

Core FEA Objects

1. Node (Finite Element Node)

Nodes are points in space with 6 degrees of freedom (3 translations + 3 rotations).

Object Type: Node Prefix: NODE

Key Properties

Property

Type

Description

Default

Coordinates

X, Y, Z

Number

Global coordinates

XLocal, YLocal, ZLocal

Number

Alignment-based coordinates (relative to bridge alignment/station)

CoorSys

OpenBrIM.CoorSys

Coordinate system reference

Constraints

Tx, Ty, Tz

Number

Translation constraints

0 (free)

Rx, Ry, Rz

Number

Rotation constraints

0 (free)

Node Linking

TxLink, TyLink, TzLink

Node

Couple translation DOF to another node

RxLink, RyLink, RzLink

Node

Couple rotation DOF to another node

Gaps

TxGap, TyGap, TzGap

Number

Gap distance for nonlinear contact

RxGap, RyGap, RzGap

Number

Rotational gap

Stiffness

StiffnessMatrix

6x6 Matrix

Custom stiffness matrix

Grouping

Group

FEGroup

Element group membership

Constraint Encoding

Constraint values have special meanings:

-1: Free (completely unconstrained)
0: Free (same as -1, default)
1: Fixed (fully restrained)
Positive value: Spring stiffness (units: Force/Length for translations, Force*Length/Radian for rotations)

Spring Stiffness Formula:

XML Examples

Simple Pinned Support (Fixed translations, free rotations):

Fixed Support (All DOF restrained):

Spring Support:

6x6 Stiffness Matrix Support:

Linked Nodes (Slave-Master Relationship):

Advanced Node Attributes

MergeNearest - Controls node merging behavior during mesh compilation:

MergeSameLoc - Controls automatic merging of coincident nodes:

Best Practices:

Set MergeNearest=false (default) for all primary structural nodes
Set MergeNearest=true for load application points and boundary condition nodes
Set MergeSameLoc=false only when you need separate nodes at identical coordinates (e.g., hinges, springs)
Use StiffnessMatrix for complex foundation springs with coupled DOF behavior
For simple uncoupled springs, use individual Tx/Ty/Tz/Rx/Ry/Rz values instead

2. FELine (Beam/Truss Element)

1D finite elements connecting two nodes. Supports beams, trusses, cables, and inelastic elements.

Object Type: FELine Prefix: LINE

Element Types

FEType property values:

0 (BEAM): Beam element with bending, axial, and shear
1 (TRUSS): Truss element (axial only, pin-pin)
2 (COMPTRUSS): Compression-only truss
3 (TENSTRUSS): Tension-only truss
4 (CABLE): Cable element (tension-only, catenary)
5 (INELASTIC): Inelastic beam (plastic hinges)

Key Properties

Property

Type

Description

Default

Connectivity

Node1, Node2

Node

End nodes

Required

Element Type

FEType

FELineType

Element formulation

BEAM

Cross-Section

Sec

SEC.Section

Primary cross-section

Required

Sec2

SEC.Section

Secondary section at Node2 (tapered)

SecN

Text

Section reference name

Material

Material

MAT.Material

Material reference

PropMatE

Number

Young's modulus override

PropMatNu

Number

Poisson's ratio override

Orientation

Orientation

Number

Rotation angle around element axis (radians)

Offsets

Node1OffX, Node1OffY, Node1OffZ

Number

Global offset at Node1

Node2OffX, Node2OffY, Node2OffZ

Number

Global offset at Node2

Node1LocalOffX/Y/Z

Number

Local offset at Node1

Node2LocalOffX/Y/Z

Number

Local offset at Node2

End Releases

Node1Tx through Node1Rz

Number

Release at Node1 (6 DOF)

Node2Tx through Node2Rz

Number

Release at Node2 (6 DOF)

useLocalRelease

Boolean

Releases in local coordinates (note the lower-case u — the name is case-sensitive)

false

Grouping

Group

FEGroup

Element group

End Release Encoding

End release values have special meanings:

-1: Released (free, hinge)
0: Connected (rigid connection, default)
Positive value: Rotational spring stiffness

Common Release Patterns:

Pin-Pin Truss: Node1Rz=-1, Node2Rz=-1
Cantilever End: Node2Rx=-1, Node2Ry=-1, Node2Rz=-1
Semi-Rigid Connection: Node2Rz=50000 (spring stiffness)

XML Examples

Simple Beam:

Truss Element:

Beam with End Releases (Simple Support):

Tapered Beam:

Beam with Offsets:

Advanced FELine Attributes

IsRigid - Creates rigid elements with infinite stiffness:

Use Cases for Rigid Elements:

Rigid end offsets for eccentric connections
Rigid diaphragms
Master-slave constraints
Rigid zones at beam-column connections

Best Practices:

Still requires a Section assignment (though properties are ignored)
Use short lengths to minimize numerical issues
Set BetaAngle appropriately even for rigid elements

BetaAngle - Rotates local element coordinate system about longitudinal axis:

Element Local Coordinate System:

X-axis: Along element (Node1 → Node2)
Y-axis: Perpendicular to X, default vertical
Z-axis: Right-hand rule from X and Y
BetaAngle: Rotation about X-axis (radians)

When BetaAngle is Critical:

I-beams, channels, and asymmetric sections
Skewed bridges
Members with specific orientation requirements
Wind/seismic load direction alignment

Caution: Incorrect BetaAngle can cause strong-axis bending in the weak direction!

CastingDay - Defines when concrete was cast for time-dependent analysis:

Staged Construction Analysis:

How CastingDay Works:

Element age = Current Stage Day - CastingDay
Used to calculate concrete strength, modulus, creep, and shrinkage
Elements must be cast (age ≥ 0) before being loaded
Different ages produce different time-dependent behavior

Applications:

Staged construction modeling
Creep and shrinkage analysis
Concrete strength gain over time
Construction sequence effects

Node Release Patterns:

The end release properties (Node1Rx through Node2Rz) control connection behavior:

Values:

-1: Released (free, pin)
0: Connected (rigid, default for most)
Positive value: Semi-rigid spring stiffness

Common Connection Types:

Best Practices for Releases:

Always specify releases at both ends for clarity
Use 0 for true pin connections (moment release)
Use positive values for semi-rigid connections based on research/testing
Verify connection behavior matches structural design intent
For cap-to-column connections, match releases to design assumptions (fixed vs. pinned)

3. FESurface (Shell Element)

2D finite elements for plates and shells. Supports quadrilateral (4-node) and triangular (3-node) elements with membrane and bending behavior.

Object Type: FESurface Prefix: SURF

Key Properties

Property

Type

Description

Default

Connectivity

Node1, Node2, Node3, Node4

Node

Corner nodes (counter-clockwise)

Required

Material

Mat

MAT.Material

Material reference

Required

PropMatE

Number

Young's modulus override

PropMatNu

Number

Poisson's ratio override

Geometry

Thickness

Number

Shell thickness

Required

PropTh

Number

Thickness override; applies to stiffness AND self-weight/mass

PropThStiff

Number

Stiffness-only thickness override; weight, mass and geometry stay on Thickness/PropTh. 0 = unset

Offsets

Node1-4 OffX, OffY, OffZ

Number

Global offsets at corners

Node1-4 LocalOffX/Y/Z

Number

Local offsets at corners

Grouping

Group

FEGroup

Element group

XML Examples

Quadrilateral Shell:

Triangular Shell:

4. FESpring (Spring Element)

Zero-length spring or connector element with custom stiffness properties.

Object Type: FESpring Prefix: SPRING

Key Properties

Property

Type

Description

Default

Connectivity

Node1, Node2

Node

Connected nodes (can be same node)

Required

Stiffness

Tx, Ty, Tz

Number

Translational stiffness (Force/Length)

Rx, Ry, Rz

Number

Rotational stiffness (Force*Length/Radian)

StiffnessMatrix

6x6 Matrix

Custom stiffness matrix

Gaps

TxGap, TyGap, TzGap

Number

Gap distance for compression/tension

RxGap, RyGap, RzGap

Number

Rotational gap

Grouping

Group

FEGroup

Element group

XML Examples

Simple Vertical Spring:

6-DOF Spring:

Gap Element (Compression Only):

5. FEGroup (Element Grouping)

Hierarchical groups for organizing FE objects. Groups can filter elements based on ParamML expressions.

Object Type: FEGroup Prefix: GROUP

Key Properties

Property

Type

Description

Default

Name

Text

Group name

Required

ParentGroup

FEGroup or Array

Parent group(s)

Filter

ParamML.Param

Filter expression

AlignmentN

Text

Alignment reference name

XML Examples

Simple Group:

Filtered Group:

Hierarchical Groups:

FEGroup Quick Pattern (Bridge-Level Selection)

Bridge-level groups: Define per-type FEGroups on the bridge (e.g., TrussFEGroup, CrossFrameFEGroup, DeckFEGroup). Child objects do not create their own groups; they use the bridge FEGroup as ParentGroup.
Location identity + filter: Export endpoints (locx1..locz2) and stamp FE elements (the Line inside FELine/FEMeshLine) with X1..Z2. Example filtered group and FELine:
FEMeshLine note (X1..Z2 on Line):
Selection step: Construction/Deconstruction collects the selected *_fegroup_fltrd entries with removedup(map(...)), wraps them in a ParentGroup FEGroup, and points StructureState to that wrapper; a Guard skips when nothing is selected.
Loads: Use per-type load FEGroup (e.g., Truss_Temp, CrossFrame_Temp); set ParentGroup to the bridge counterpart; aim TemperatureLoad at that FEGroup.
Purpose: Default expectation is to act on the selected elements and avoid “everything shares one FEGroup” mistakes. If a step is meant to hit all elements (bridge-scope or mode-based like partial/complete), set selection scope accordingly (selected-only or all).

Mesh Generation Objects

1. FEMesh (Automatic Meshing)

FEMesh manages automatic discretization of geometry into finite elements.

Mesh Data Format

Automatic meshing produces nodes and elements in the following format:

Nodes: Array of [X, Y, Z] coordinates

Elements: Arrays of node indices (0-based)

lines: 2-node line elements [[n1, n2], ...]
triangles: 3-node triangular shells [[n1, n2, n3], ...]
quads: 4-node quadrilateral shells [[n1, n2, n3, n4], ...]

Note: Element connectivity uses 0-based indexing into the nodes array.

Load Objects

1. AnalysisCase (Base Load Case)

Base class for all analysis types. Contains load case metadata and configuration.

Object Type: AnalysisCase Prefix: SLC (Static Load Case)

Load Type Values

Common LoadType values:

Dead Loads: DL, IL, DW
Live Loads: LL, LP, LLI, LLL, LLP, LLS, LLF, BR, LLH, LLAG, LLPV, LLR
Wind: WS, WL, WI
Seismic: EQ, EL, EP, EV, EH, DD, ES
Prestress: PS, PSLR, PSLO, PSAL
Time-Dependent: SH (Shrinkage), CR (Creep), TU (Temperature)
Construction: CDL, CIL, CLL, CWS, CH, CM
Other: SL (Snow), CT/CV/CE (Collision), RS (Stream), BU (Buoyancy), SFP (Stream Flow), IC (Ice), BL (Blast)

Key Properties

Property

Type

Description

Default

Identification

Name

Text

Load case name

Required

AnalysisID

Text

Unique analysis identifier

Auto

LoadType

LoadTypeEnum

Load classification

None

Analysis Control

Active

Boolean

Enable this analysis

true

Nonlinear

Boolean

Nonlinear analysis

false

Steps

Number

Max load steps

Iterations

Number

Max iterations per step

ForceTolerance

Number

Force convergence tolerance

0.001

DisplacementTolerance

Number

Displacement tolerance

0.001

Element Selection

ActiveGroup

FEGroup

Elements to analyze

Group

FEGroup

Load application group

XML Example

2. NodeLoad (Point Load on Nodes)

Concentrated forces and moments applied to nodes.

Object Type: NodeLoad Prefix: NLOAD

Key Properties

Property

Type

Description

Default

AnalysisCase

Parent load case

Required

Node

Node or FEGroup

Target node(s)

Required

Fx, Fy, Fz

Number

Force components

Mx, My, Mz

Number

Moment components

Sys

Number

Coordinate system (0=Global, 1=Local)

XML Examples

Vertical Point Load:

Load on Multiple Nodes (via Group):

Moment Load:

3. PointLoad (Load on Surface)

Load applied at a specific point on FE surfaces. Automatically distributed to underlying elements/nodes.

Object Type: PointLoad Prefix: PLOAD

Key Properties

Property

Type

Description

Default

AnalysisCase

Parent load case

Required

Group

FEGroup

Target surface group

Required

PointX, PointY

Number

Load location on surface

Fx, Fy, Fz

Number

Force components

Mx, My, Mz

Number

Moment components

XML Example

4. Combination (Load Combination)

Linear combination of analysis cases with factors.

Object Type: Combination Prefix: COMB

A combination contains multiple CombinationItem child objects, each specifying a load case and factor.

XML Example

Analysis Types

1. Static Linear Analysis

Basic linear elastic analysis. Default analysis type.

Configuration

Use base AnalysisCase object with:

Nonlinear = false (default)
Steps = 1 (single step)

XML Example

Extract natural frequencies and mode shapes.

Object Type: AnalysisCaseEigen Prefix: SLC

Mode Extraction Methods

ModeType property values:

"Eigen": Standard eigenvalue extraction
"RitzWYD": Wilson-Yuan-Dickens Ritz vectors
"RitzLWYD": Leger-Wilson-Clough Ritz vectors
"RitzQSRV": Quasi-Static Ritz Vectors (frequency-shifted)

Key Properties

Property

Type

Description

Default

Mode Extraction

Modes

Number

Number of modes to extract

ModeType

Extraction method

"Eigen"

Gravity

Number

Gravitational acceleration

386.088583

DenseSolver

Boolean

Use dense eigenvalue solver

false

Mass Sources

SelfMassFactor

Number

Self-weight mass factor

1.0

MassCase1-5

AnalysisCase

Additional mass from loads

MassCaseFactor1-5

Number

Mass case factors

1.0

Ritz Parameters

AppliedLoad

AnalysisCase

Load pattern for Ritz methods

CenteringFreq

Number

Centering frequency for QSRV (rad/s)

Response Spectrum

Curve1, Curve2, Curve3

ResponseSpectrumCurve

Spectrum curves (3 directions)

Scale1, Scale2, Scale3

Number

Direction scale factors

1.0

BetaAngle

Number

Direction rotation angle (radians)

DampingRatio

Number

Constant damping ratio

0.05

DampingCurve

ResponseSpectrumCurve

Variable damping vs frequency

Modal Combination

ModalCombType

ResponseSpectrumModalCombMethod

CQC or SRSS

SpatialCombType

ResponseSpectrumSpatialCombMethod

ABS or SRSS

Modal Combination Methods:

CQC: Complete Quadratic Combination (accounts for modal coupling, use for closely-spaced modes)
SRSS: Square Root of Sum of Squares (assumes uncoupled modes)

Spatial Combination Methods:

ABS: Absolute Sum
SRSS: Square Root of Sum of Squares

Mass Assembly

Total mass matrix assembled from:

Self Mass: Element mass from self-weight
Load Case Mass: Vertical forces converted to mass
Nodal Mass: Explicit mass objects (NodeMass)

NodeMass Object

Object Type: NodeMass Prefix: MASS

Output

Frequencies Table for each mode:

Mode number (1-based)
Frequency (Hz)
Period (seconds)
Cumulative mass participation X, Y, Z (%)
Participation factors X, Y, Z

Mode Shapes stored as displacement results in AnalysisCaseEigenMode objects.

XML Examples

Basic Modal Analysis:

Ritz Vector Analysis:

3. Response Spectrum Analysis

Seismic analysis using response spectrum curves.

ResponseSpectrumCurve Object

Object Type: ResponseSpectrumCurve Prefix: RSAC

Property

Type

Description

Default

Name

Text

Curve name

Required

XAxis

"time" or "frequency"

X-axis type (period or frequency)

"time"

YAxis

"acceleration"

Y-axis type

"acceleration"

MaxX

Number

Maximum period/frequency

Curve Data: Define as child Point objects where:

X = Period (seconds) or Frequency (Hz)
Y = Spectral acceleration (g's)

Response Spectrum Configuration

Uses AnalysisCaseEigen with spectrum curves defined.

XML Examples

Response Spectrum Curve (ASCE 7):

Response Spectrum Analysis:

4. Pushover Analysis

Nonlinear static pushover analysis for seismic performance evaluation.

Object Type: AnalysisCasePushover Prefix: PUSH

Key Properties

Property

Type

Description

Default

Control

Node

Reference control node

Required

RefNodeGroup

FEGroup

Or group of control nodes

Dir

Number

Control direction (0-5: Fx,Fy,Fz,Mx,My,Mz)

Required

Disp

Number

Target displacement

DispControl

Boolean

Use displacement control

false

Load Control

InitFactor

Number

Initial load factor

Increment

Number

Load factor increment

Solver Settings

Steps

Number

Maximum number of steps

100

Iterations

Number

Max iterations per step

Overview

Core Concepts

1. FEA Object Hierarchy

2. Coordinate Systems

3. Degrees of Freedom (DOF)

Core FEA Objects

1. Node (Finite Element Node)

Key Properties

Constraint Encoding

XML Examples

Advanced Node Attributes

2. FELine (Beam/Truss Element)

Element Types

Key Properties

End Release Encoding

XML Examples

Advanced FELine Attributes

3. FESurface (Shell Element)

Key Properties

XML Examples

4. FESpring (Spring Element)

Key Properties

XML Examples

5. FEGroup (Element Grouping)

Key Properties

XML Examples

FEGroup Quick Pattern (Bridge-Level Selection)

Mesh Generation Objects

1. FEMesh (Automatic Meshing)

Mesh Data Format

Load Objects

1. AnalysisCase (Base Load Case)

Load Type Values

Key Properties

XML Example

2. NodeLoad (Point Load on Nodes)

Key Properties

XML Examples

3. PointLoad (Load on Surface)

Key Properties

XML Example

4. Combination (Load Combination)

XML Example

Analysis Types

1. Static Linear Analysis

Configuration

XML Example

2. Eigenvalue/Modal Analysis

Mode Extraction Methods

Key Properties

Mass Assembly

NodeMass Object

Output

XML Examples

3. Response Spectrum Analysis

ResponseSpectrumCurve Object

Response Spectrum Configuration

XML Examples

4. Pushover Analysis

Key Properties