# 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                                                 | 0        |
| XLocal, YLocal, ZLocal | Number           | Alignment-based coordinates (relative to bridge alignment/station) | 0        |
| 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                                 | 0        |
| RxGap, RyGap, RzGap    | Number           | Rotational gap                                                     | 0        |
| **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:**

```
For linear springs: k = Force / Displacement
Use actual stiffness value as constraint value
```

#### XML Examples

**Simple Pinned Support (Fixed translations, free rotations):**

```xml
<O T="Node" N="Support1" X="0" Y="0" Z="0" Tx="1" Ty="1" Tz="1" Rx="0" Ry="0" Rz="0"/>
```

**Fixed Support (All DOF restrained):**

```xml
<O T="Node" N="Support2" X="100" Y="0" Z="0" Tx="1" Ty="1" Tz="1" Rx="1" Ry="1" Rz="1"/>
```

**Spring Support:**

```xml
<O T="Node" N="SpringNode" X="50" Y="0" Z="0" Tx="0" Ty="0" Tz="10000" Rx="0" Ry="0" Rz="0"/>
<!-- Tz=10000: Spring in Z with k=10000 (Force/Length units) -->
```

**6x6 Stiffness Matrix Support:**

```xml
<P N="stiffness_matrix" V="[
  [1000, 0, 0, 0, 0, 0],
  [1000, 0, 0, 0, 0],
  [5000, 0, 0, 0],
  [500, 0, 0],
  [500, 0],
  [500]
]"/>  <!-- Upper triangular, symmetric matrix -->

<O T="Node" N="FoundationNode" X="0" Y="0" Z="0" StiffnessMatrix="stiffness_matrix"/>
<!-- Provides coupled spring support in all 6 DOF -->
```

**Linked Nodes (Slave-Master Relationship):**

```xml
<O T="Node" N="MasterNode" X="0" Y="0" Z="0"/>

<O T="Node" N="SlaveNode" X="0" Y="10" Z="0">
  <P N="TxLink" V="@MasterNode|Node" T="Node"/>  <!-- Tx coupled to MasterNode Tx -->
  <P N="TyLink" V="@MasterNode|Node" T="Node"/>  <!-- Ty coupled to MasterNode Ty -->
</O>
```

#### Advanced Node Attributes

**MergeNearest** - Controls node merging behavior during mesh compilation:

```xml
<!-- Primary structural nodes (define merge locations) -->
<O T="Repeat" N="BeamNodes" S="0" E="10" I="1" CTRL="i" i="0">
  <O T="Node" N="NODE" X="i*12" Y="0" Z="0" MergeNearest="0"/>
</O>

<!-- Secondary node (merges to nearest primary node) -->
<O T="Node" N="LoadNode" X="5.2" Y="0.1" Z="0" MergeNearest="1"/>
<!-- This node will snap to the nearest primary node -->
```

**MergeSameLoc** - Controls automatic merging of coincident nodes:

```xml
<!-- Separate nodes at same location for pinned connection -->
<O T="Node" N="ColumnTop" X="100" Y="50" Z="200" MergeSameLoc="0"/>
<O T="Node" N="BeamEnd" X="100" Y="50" Z="200" MergeSameLoc="0"/>
<O T="FESpring" Node1="@ColumnTop|Node" Node2="@BeamEnd|Node"
   Rx="0" Ry="0" Rz="0.001"/>  <!-- Pinned connection via spring -->
```

**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) | 0        |
| **Offsets**                     |              |                                              |          |
| Node1OffX, Node1OffY, Node1OffZ | Number       | Global offset at Node1                       | 0        |
| Node2OffX, Node2OffY, Node2OffZ | Number       | Global offset at Node2                       | 0        |
| Node1LocalOffX/Y/Z              | Number       | Local offset at Node1                        | 0        |
| Node2LocalOffX/Y/Z              | Number       | Local offset at Node2                        | 0        |
| **End Releases**                |              |                                              |          |
| Node1Tx through Node1Rz         | Number       | Release at Node1 (6 DOF)                     | 0        |
| Node2Tx through Node2Rz         | Number       | Release at Node2 (6 DOF)                     | 0        |
| UseLocalRelease                 | Boolean      | Releases in local coordinates                | 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:**

```xml
<O T="FELine" N="Beam1">
  <P N="Node1" V="@NODE_1|Node" T="Node"/>
  <P N="Node2" V="@NODE_2|Node" T="Node"/>
  <P N="FEType" V="0"/>  <!-- BEAM -->
  <P N="Sec" V="@W24x76|SEC.Section" T="Section"/>
</O>
```

**Truss Element:**

```xml
<O T="FELine" N="Truss1" FEType="1">  <!-- TRUSS -->
  <P N="Node1" V="@NODE_3|Node" T="Node"/>
  <P N="Node2" V="@NODE_4|Node" T="Node"/>
  <P N="Sec" V="@Angle_4x4|SEC.Section" T="Section"/>
</O>
```

**Beam with End Releases (Simple Support):**

```xml
<O T="FELine" N="SimpleBeam">
  <P N="Node1" V="@NODE_1|Node" T="Node"/>
  <P N="Node2" V="@NODE_2|Node" T="Node"/>
  <P N="Sec" V="@W24x76|SEC.Section" T="Section"/>

  <!-- Release rotations at both ends (pin-pin) -->
  <P N="Node1Rz" V="-1"/>  <!-- Hinge at start -->
  <P N="Node2Rz" V="-1"/>  <!-- Hinge at end -->
</O>
```

**Tapered Beam:**

```xml
<O T="FELine" N="TaperedBeam">
  <P N="Node1" V="@NODE_1|Node" T="Node"/>
  <P N="Node2" V="@NODE_2|Node" T="Node"/>
  <P N="Sec" V="@W24x76|SEC.Section" T="Section"/>   <!-- Section at Node1 -->
  <P N="Sec2" V="@W30x90|SEC.Section" T="Section"/>  <!-- Section at Node2 -->
</O>
```

**Beam with Offsets:**

```xml
<O T="FELine" N="OffsetBeam">
  <P N="Node1" V="@NODE_1|Node" T="Node"/>
  <P N="Node2" V="@NODE_2|Node" T="Node"/>
  <P N="Sec" V="@W24x76|SEC.Section" T="Section"/>

  <!-- Offset beam below node line by 12 inches -->
  <P N="Node1LocalOffZ" V="-12"/>
  <P N="Node2LocalOffZ" V="-12"/>
</O>
```

#### Advanced FELine Attributes

**IsRigid** - Creates rigid elements with infinite stiffness:

```xml
<!-- Rigid link from column to cap -->
<P N="rigid_sec" V="@RigidSection|Section" T="Section"/>
<O T="FELine" N="RigidOffset" IsRigid="1"
   Node1="@ColumnTop|Node"
   Node2="@CapNode|Node"
   Sec="@rigid_sec|Section"
   BetaAngle="0"/>
<!-- Acts as a rigid body constraint, ignoring section 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:

```xml
<!-- Column with 90-degree rotation -->
<O T="FELine" N="Column"
   Node1="@BottomNode|Node"
   Node2="@TopNode|Node"
   Sec="@RectangularSection|Section"
   BetaAngle="PI/2"/>  <!-- Rotates local Y and Z axes by 90 degrees -->

<!-- Girder aligned with bridge skew -->
<P N="skew_angle" V="15 * PI / 180"/>  <!-- 15 degrees in radians -->
<O T="FELine" N="Girder"
   Node1="@Node1|Node"
   Node2="@Node2|Node"
   Sec="@IBeamSection|Section"
   BetaAngle="skew_angle"/>
```

**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:

```xml
<!-- Pile foundation cast on day 0 -->
<O T="FELine" N="Pile"
   Node1="@PileTop|Node"
   Node2="@PileBot|Node"
   Sec="@PileSection|Section"
   CastingDay="0"/>

<!-- Column cast on day 30 -->
<O T="FELine" N="Column"
   Node1="@ColBot|Node"
   Node2="@ColTop|Node"
   Sec="@ColumnSection|Section"
   CastingDay="30"/>

<!-- Girder cast on day 60 -->
<O T="FELine" N="Girder"
   Node1="@GirderStart|Node"
   Node2="@GirderEnd|Node"
   Sec="@GirderSection|Section"
   CastingDay="60"/>
```

**Staged Construction Analysis:**

```xml
<!-- Stage 1: Day 30 - Activate columns -->
<O T="AnalysisStage" N="Stage1" Day="30">
  <!-- Columns have age = 30-30 = 0 days (just cast) -->
</O>

<!-- Stage 2: Day 60 - Activate girders -->
<O T="AnalysisStage" N="Stage2" Day="60">
  <!-- Column age = 60-30 = 30 days -->
  <!-- Girder age = 60-60 = 0 days (just cast) -->
</O>

<!-- Stage 3: Day 90 - Apply deck load -->
<O T="AnalysisStage" N="Stage3" Day="90">
  <!-- Column age = 90-30 = 60 days (creep/shrinkage) -->
  <!-- Girder age = 90-60 = 30 days (different creep) -->
  <!-- Apply long-term dead load -->
</O>
```

**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:**

```xml
<!-- Pin-Pin Beam (all rotations released) -->
<O T="FELine" N="SimpleSupportedBeam"
   Node1="@Left|Node" Node2="@Right|Node"
   Sec="@BeamSec|Section"
   Node1Rx="0" Node1Ry="0" Node1Rz="0"
   Node2Rx="0" Node2Ry="0" Node2Rz="0"/>

<!-- Column with pinned base, fixed top -->
<O T="FELine" N="Column"
   Node1="@Base|Node" Node2="@Top|Node"
   Sec="@ColumnSec|Section"
   Node1Rx="0" Node1Ry="0" Node1Rz="0"     <!-- Pinned base -->
   Node2Rx="-1" Node2Ry="-1" Node2Rz="-1"/> <!-- Fixed top -->

<!-- Truss member (axial only, all rotations released) -->
<O T="FELine" N="Truss" FEType="1"
   Node1="@Joint1|Node" Node2="@Joint2|Node"
   Sec="@AngleSec|Section"
   Node1Rx="0" Node1Ry="0" Node1Rz="0"
   Node2Rx="0" Node2Ry="0" Node2Rz="0"/>

<!-- Semi-rigid connection (partial moment transfer) -->
<O T="FELine" N="BeamToColumn"
   Node1="@Column|Node" Node2="@Beam|Node"
   Sec="@BeamSec|Section"
   Node2Ry="5000"/>  <!-- 5000 Force*Length/Radian rotational stiffness -->
```

**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       | Property thickness override      | -        |
| **Offsets**                |              |                                  |          |
| Node1-4 OffX, OffY, OffZ   | Number       | Global offsets at corners        | 0        |
| Node1-4 LocalOffX/Y/Z      | Number       | Local offsets at corners         | 0        |
| **Grouping**               |              |                                  |          |
| Group                      | FEGroup      | Element group                    | -        |

#### XML Examples

**Quadrilateral Shell:**

```xml
<O T="FESurface" N="Shell1">
  <P N="Node1" V="@NODE_1|Node" T="Node"/>
  <P N="Node2" V="@NODE_2|Node" T="Node"/>
  <P N="Node3" V="@NODE_3|Node" T="Node"/>
  <P N="Node4" V="@NODE_4|Node" T="Node"/>
  <P N="Thickness" V="8"/>  <!-- 8 inch slab -->
  <P N="Mat" V="@Concrete_4ksi|MAT.Material" T="Material"/>
</O>
```

**Triangular Shell:**

```xml
<O T="FESurface" N="TriShell1">
  <P N="Node1" V="@NODE_1|Node" T="Node"/>
  <P N="Node2" V="@NODE_2|Node" T="Node"/>
  <P N="Node3" V="@NODE_3|Node" T="Node"/>
  <!-- Node4 not defined for triangular elements -->
  <P N="Thickness" V="6"/>
  <P N="Mat" V="@Concrete_4ksi|MAT.Material" T="Material"/>
</O>
```

***

### 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)      | 0        |
| Rx, Ry, Rz          | Number     | Rotational stiffness (Force\*Length/Radian) | 0        |
| StiffnessMatrix     | 6x6 Matrix | Custom stiffness matrix                     | -        |
| **Gaps**            |            |                                             |          |
| TxGap, TyGap, TzGap | Number     | Gap distance for compression/tension        | 0        |
| RxGap, RyGap, RzGap | Number     | Rotational gap                              | 0        |
| **Grouping**        |            |                                             |          |
| Group               | FEGroup    | Element group                               | -        |

#### XML Examples

**Simple Vertical Spring:**

```xml
<O T="FESpring" N="VertSpring1">
  <P N="Node1" V="@NODE_Base|Node" T="Node"/>
  <P N="Node2" V="@NODE_Deck|Node" T="Node"/>
  <P N="Tz" V="50000"/>  <!-- Vertical spring, k=50000 -->
</O>
```

**6-DOF Spring:**

```xml
<O T="FESpring" N="FullSpring">
  <P N="Node1" V="@NODE_1|Node" T="Node"/>
  <P N="Node2" V="@NODE_2|Node" T="Node"/>
  <P N="Tx" V="10000"/>
  <P N="Ty" V="10000"/>
  <P N="Tz" V="50000"/>
  <P N="Rx" V="100000"/>
  <P N="Ry" V="100000"/>
  <P N="Rz" V="100000"/>
</O>
```

**Gap Element (Compression Only):**

```xml
<O T="FESpring" N="GapElement">
  <P N="Node1" V="@NODE_1|Node" T="Node"/>
  <P N="Node2" V="@NODE_2|Node" T="Node"/>
  <P N="Tz" V="1000000"/>  <!-- High stiffness in compression -->
  <P N="TzGap" V="0.1"/>    <!-- 0.1 inch gap before engagement -->
</O>
```

***

### 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:**

```xml
<O T="FEGroup" N="All_Girders">
  <!-- Elements reference this group via Group property -->
</O>
```

**Filtered Group:**

```xml
<O T="FEGroup" N="Long_Beams">
  <P N="Filter" V="Length > 100"/>  <!-- ParamML expression -->
</O>
```

**Hierarchical Groups:**

```xml
<O T="FEGroup" N="Superstructure"/>

<O T="FEGroup" N="Girders">
  <P N="ParentGroup" V="@Superstructure|FEGroup"/>
</O>

<O T="FEGroup" N="Deck">
  <P N="ParentGroup" V="@Superstructure|FEGroup"/>
</O>
```

#### 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:

  ```xml
  <P N="locx1" V="ptA[0]"/><!-- ... locz2 -->
  <P N="bridge_trussgroup" V="bridge.TrussFEGroup" T="FEGroup"/>
  <O N="truss_fegroup_fltrd" T="FEGroup">
    <P N="ParentGroup" V="bridge_trussgroup" T="FEGroup"/>
    <P N="Filter" V="x.X1 .EQ. locx1 .AND. x.X2 .EQ. locx2 .AND. x.Y1 .EQ. locy1 .AND. x.Y2 .EQ. locy2 .AND. x.Z1 .EQ. locz1 .AND. x.Z2 .EQ. locz2"/>
  </O>
  <O T="FELine" Group="@bridge_trussgroup|FEGroup" X1="locx1" Y1="locy1" Z1="locz1" X2="locx2" Y2="locy2" Z2="locz2"/>
  ```
* **FEMeshLine note (X1..Z2 on Line):**

  ```xml
  <O T="FEMeshLine" Group="@bridge_trussgroup|FEGroup">
    <O T="Repeat" E="len-1" S="1" I="1" CTRL="i" i="1">
      <O T="Line" PolyLine="1" X1="locx1" Y1="locy1" Z1="locz1" X2="locx2" Y2="locy2" Z2="locz2">
        <O T="Point" X="pts[i-1][0]" Y="pts[i-1][1]" Z="pts[i-1][2]" />
        <O T="Point" X="pts[i][0]" Y="pts[i][1]" Z="pts[i][2]" />
      </O>
    </O>
  </O>
  ```
* **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

```
[[x1, y1, z1], [x2, y2, z2], ...]
```

**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              | 1        |
| Iterations            | Number       | Max iterations per step     | 50       |
| 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

```xml
<O T="AnalysisCase" N="Dead Load">
  <P N="AnalysisID" V="DL_1"/>
  <P N="LoadType" V="DL"/>  <!-- Dead load -->
  <P N="Active" V="1"/>
  <P N="ActiveGroup" V="@All_Structure|FEGroup"/>
</O>
```

***

### 2. NodeLoad (Point Load on Nodes)

Concentrated forces and moments applied to nodes.

**Object Type:** `NodeLoad` **Prefix:** `NLOAD`

#### Key Properties

| Property   | Type            | Description                           | Default  |
| ---------- | --------------- | ------------------------------------- | -------- |
| LC         | AnalysisCase    | Parent load case                      | Required |
| Node       | Node or FEGroup | Target node(s)                        | Required |
| Fx, Fy, Fz | Number          | Force components                      | 0        |
| Mx, My, Mz | Number          | Moment components                     | 0        |
| Sys        | Number          | Coordinate system (0=Global, 1=Local) | 0        |

#### XML Examples

**Vertical Point Load:**

```xml
<O T="NodeLoad" N="ConcLoad1">
  <P N="LC" V="@LiveLoad_1|AnalysisCase" T="AnalysisCase"/>
  <P N="Node" V="@NODE_MidSpan|Node" T="Node"/>
  <P N="Fz" V="-10000"/>  <!-- 10 kip downward -->
  <P N="Sys" V="0"/>      <!-- Global coordinates -->
</O>
```

**Load on Multiple Nodes (via Group):**

```xml
<O T="NodeLoad" N="LoadGroup">
  <P N="LC" V="@Dead Load|AnalysisCase" T="AnalysisCase"/>
  <P N="Node" V="@Top_Nodes|FEGroup" T="FEGroup"/>  <!-- Applied to all nodes in group -->
  <P N="Fz" V="-1000"/>
</O>
```

**Moment Load:**

```xml
<O T="NodeLoad" N="MomentLoad1">
  <P N="LC" V="@LiveLoad_1|AnalysisCase" T="AnalysisCase"/>
  <P N="Node" V="@NODE_1|Node" T="Node"/>
  <P N="My" V="50000"/>  <!-- Moment about Y axis -->
</O>
```

***

### 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  |
| -------------- | ------------ | ------------------------ | -------- |
| LC             | AnalysisCase | Parent load case         | Required |
| Group          | FEGroup      | Target surface group     | Required |
| PointX, PointY | Number       | Load location on surface | 0        |
| Fx, Fy, Fz     | Number       | Force components         | 0        |
| Mx, My, Mz     | Number       | Moment components        | 0        |

#### XML Example

```xml
<O T="PointLoad" N="DeckPointLoad">
  <P N="LC" V="@LiveLoad_1|AnalysisCase"/>
  <P N="Group" V="@Deck_Shells|FEGroup"/>
  <P N="PointX" V="60"/>   <!-- X location on surface -->
  <P N="PointY" V="20"/>   <!-- Y location on surface -->
  <P N="Fz" V="-16000"/>   <!-- 16 kip downward -->
</O>
```

***

### 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

```xml
<O T="Combination" N="Service_I">
  <O T="CombinationItem">
    <P N="Case" V="@Dead_Load|AnalysisCase"/>
    <P N="Factor" V="1.0"/>
  </O>
  <O T="CombinationItem">
    <P N="Case" V="@Live_Load|AnalysisCase"/>
    <P N="Factor" V="1.75"/>
  </O>
  <O T="CombinationItem">
    <P N="Case" V="@Wind_Load|AnalysisCase"/>
    <P N="Factor" V="0.5"/>
  </O>
</O>
```

***

## 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

```xml
<O T="AnalysisCase" N="Dead Load">
  <P N="AnalysisID" V="DL"/>
  <P N="LoadType" V="DL"/>
  <P N="Active" V="1"/>
  <P N="Nonlinear" V="0"/>
  <P N="ActiveGroup" V="@All_Structure|FEGroup"/>
</O>

<!-- Add loads to this case -->
<O T="NodeLoad" N="SelfWeight">
  <P N="LC" V="@Dead Load|AnalysisCase"/>
  <!-- ... -->
</O>
```

***

### 2. Eigenvalue/Modal Analysis

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           | 1          |
| ModeType               | 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)   | 0          |
| 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:

1. **Self Mass**: Element mass from self-weight

   ```
   M_self = (Element Mass) * SelfMassFactor / Gravity
   ```
2. **Load Case Mass**: Vertical forces converted to mass

   ```
   M_load = Σ(Vertical Forces in MassCase_i) * MassCaseFactor_i / Gravity
   ```
3. **Nodal Mass**: Explicit mass objects (NodeMass)

#### NodeMass Object

**Object Type:** `NodeMass` **Prefix:** `MASS`

```xml
<O T="NodeMass" N="AddedMass1">
  <P N="LC" V="@Modal_Analysis|AnalysisCaseEigen" T="AnalysisCaseEigen"/>
  <P N="Node" V="@NODE_Top|Node" T="Node"/>
  <P N="Fx" V="10000"/>  <!-- Force units, converted to mass: M = F/g -->
  <P N="Fy" V="10000"/>
  <P N="Fz" V="10000"/>
  <P N="Mx" V="5000"/>   <!-- Rotational mass -->
  <P N="My" V="5000"/>
  <P N="Mz" V="5000"/>
</O>
```

#### 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:**

```xml
<O T="AnalysisCaseEigen" N="Modal Analysis">
  <P N="AnalysisID" V="MODAL"/>
  <P N="Modes" V="12"/>
  <P N="ModeType" V="Eigen"/>
  <P N="Gravity" V="386.088583"/>  <!-- in/s² for inch units -->

  <!-- Mass from self-weight -->
  <P N="SelfMassFactor" V="1.0"/>

  <!-- Additional mass from dead load -->
  <P N="MassCase1" V="@Dead_Load|AnalysisCase"/>
  <P N="MassCaseFactor1" V="1.0"/>

  <!-- Partial live load mass -->
  <P N="MassCase2" V="@Live_Load|AnalysisCase"/>
  <P N="MassCaseFactor2" V="0.25"/>

  <P N="Active" V="1"/>
  <P N="ActiveGroup" V="@All_Structure|FEGroup"/>

  <!-- Child NodeMass objects -->
  <O T="NodeMass" N="TopMass">
    <P N="Node" V="@NODE_100|Node" T="Node"/>
    <P N="Fz" V="5000"/>  <!-- Additional 5 kip mass -->
  </O>
</O>
```

**Ritz Vector Analysis:**

```xml
<O T="AnalysisCaseEigen" N="Ritz Analysis">
  <P N="Modes" V="20"/>
  <P N="ModeType" V="RitzLWYD"/>
  <P N="AppliedLoad" V="@Lateral_Load|AnalysisCase"/>  <!-- Load pattern -->
  <P N="Gravity" V="386.088583"/>
  <P N="SelfMassFactor" V="1.0"/>
</O>
```

***

### 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          | 16             |

**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):**

```xml
<O T="ResponseSpectrumCurve" N="ASCE7_Spectrum_X">
  <P N="XAxis" V="time"/>  <!-- Period-based -->
  <P N="YAxis" V="acceleration"/>
  <P N="MaxX" V="10"/>

  <!-- Define spectrum points (Period vs Acceleration) -->
  <O T="Point" X="0.0" Y="0.4"/>   <!-- Short period -->
  <O T="Point" X="0.2" Y="1.0"/>   <!-- Peak -->
  <O T="Point" X="1.0" Y="1.0"/>   <!-- Plateau -->
  <O T="Point" X="5.0" Y="0.2"/>   <!-- Long period decay -->
  <O T="Point" X="10.0" Y="0.1"/>
</O>
```

**Response Spectrum Analysis:**

```xml
<O T="AnalysisCaseEigen" N="Seismic RSA">
  <P N="AnalysisID" V="RSA"/>

  <!-- Modal parameters -->
  <P N="Modes" V="30"/>
  <P N="ModeType" V="Eigen"/>
  <P N="Gravity" V="386.088583"/>
  <P N="SelfMassFactor" V="1.0"/>

  <!-- Response Spectrum in 3 directions -->
  <P N="Curve1" V="@ASCE7_Spectrum_X|ResponseSpectrumCurve"/>
  <P N="Scale1" V="1.0"/>

  <P N="Curve2" V="@ASCE7_Spectrum_Y|ResponseSpectrumCurve"/>
  <P N="Scale2" V="1.0"/>

  <P N="Curve3" V="@ASCE7_Spectrum_Z|ResponseSpectrumCurve"/>
  <P N="Scale3" V="0.67"/>  <!-- Vertical spectrum typically 2/3 horizontal -->

  <P N="BetaAngle" V="0"/>  <!-- No rotation -->

  <!-- Damping -->
  <P N="DampingRatio" V="0.05"/>  <!-- 5% damping -->

  <!-- Combination methods -->
  <P N="ModalCombType" V="CQC"/>    <!-- Complete Quadratic Combination -->
  <P N="SpatialCombType" V="SRSS"/> <!-- SRSS for directional combination -->

  <P N="Active" V="1"/>
</O>
```

***

### 4. Pushover Analysis

Nonlinear static pushover analysis for seismic performance evaluation.

**Object Type:** `AnalysisCasePushover` **Prefix:** `PUSH`

#### Key Properties

| Property              | Type    | Description                                | Default  |
| --------------------- | ------- | ------------------------------------------ | -------- |
| **Control**           |         |                                            |          |
| Node                  | 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                        | 1        |
| DispControl           | Boolean | Use displacement control                   | false    |
| **Load Control**      |         |                                            |          |
| InitFactor            | Number  | Initial load factor                        | 1        |
| Increment             | Number  | Load factor increment                      | 1        |
| **Solver Settings**   |         |                                            |          |
| Steps                 | Number  | Maximum number of steps                    | 100      |
| Iterations            | Number  | Max iterations per step                    | 50       |
| ForceTolerance        | Number  | Force convergence tolerance                | 0.001    |
| DisplacementTolerance | Number  | Displacement tolerance                     | 0.001    |
| Nonlinear             | Boolean | Enable nonlinear analysis                  | true     |

#### XML Example

```xml
<O T="AnalysisCasePushover" N="Lateral Pushover">
  <P N="AnalysisID" V="PUSH_X"/>

  <!-- Control node and direction -->
  <P N="Node" V="@NODE_TopDeck|Node" T="Node"/>
  <P N="Dir" V="0"/>  <!-- 0=Fx (lateral X direction) -->
  <P N="Disp" V="12"/>  <!-- Target 12 inch displacement -->

  <!-- Displacement control for better convergence -->
  <P N="DispControl" V="1"/>

  <!-- Load parameters -->
  <P N="InitFactor" V="0.1"/>
  <P N="Increment" V="0.1"/>

  <!-- Solver settings -->
  <P N="Steps" V="200"/>
  <P N="Iterations" V="50"/>
  <P N="ForceTolerance" V="0.001"/>
  <P N="DisplacementTolerance" V="0.001"/>

  <P N="Nonlinear" V="1"/>
  <P N="Active" V="1"/>

  <!-- Apply lateral load pattern -->
  <O T="NodeLoad" N="PushLoad1">
    <P N="Node" V="@NODE_TopDeck|Node" T="Node"/>
    <P N="Fx" V="1000"/>  <!-- Unit load, scaled by factor -->
  </O>
</O>
```

**Output:**

* Pushover curve (load factor vs displacement)
* Step-by-step results in `AnalysisCasePushoverStep` objects
* Displacement and force results at each step

***

### 5. Staged Construction Analysis

Multi-stage construction with time-dependent material effects (creep, shrinkage, relaxation).

**Object Type:** `ConstructionStage` (extends `AnalysisCase`) **Prefix:** `STAGE`

#### Key Properties

| Property                   | Type                     | Description                       | Default |
| -------------------------- | ------------------------ | --------------------------------- | ------- |
| **Stage Sequencing**       |                          |                                   |         |
| ParentStage                | ConstructionStage        | Previous construction stage       | -       |
| ParentStageOrig            | ConstructionStage        | Original parent (skips generated) | -       |
| Day                        | Number                   | Construction day                  | 28      |
| Substage                   | Boolean                  | Is this a substage                | false   |
| **Environmental**          |                          |                                   |         |
| Temperature                | Number                   | Temperature (degrees)             | 72      |
| Humidity                   | Number                   | Humidity (%)                      | 80      |
| **Time-Dependent Effects** |                          |                                   |         |
| Creep                      | Boolean                  | Include concrete creep            | true    |
| Shrinkage                  | Boolean                  | Include shrinkage                 | true    |
| Relaxation                 | Boolean                  | Include steel relaxation          | true    |
| PTLoss                     | Boolean                  | Include PT losses                 | true    |
| TimeDepE                   | Boolean                  | Time-dependent elastic modulus    | true    |
| CreepOfTension             | Boolean                  | Creep of tensile forces           | false   |
| TimeDepModal               | Text                     | Code reference for formulas       | -       |
| **Construction**           |                          |                                   |         |
| ConstMethod                | "none", "equal", "match" | Construction method               | "none"  |
| LoadType                   | LoadTypeEnum             | Load type classification          | -       |
| Nonlinear                  | Boolean                  | Nonlinear analysis                | false   |

#### Stage Activation

Elements and supports are activated/deactivated using structure state:

**Structure State Pattern:**

* Each stage defines which groups are active/inactive
* `Stiffness` property: `true` = active, `false` = deactivated
* Active elements contribute to stiffness matrix
* Inactive elements removed from analysis

#### Load Sequencing

Loads are applied to stages using `ConstructionStageLoading` objects with properties:

* `Case`: The load case to apply
* `Factor`: Load factor (default: 1.0)

#### Time-Dependent Effects

When enabled (via boolean properties), the following effects are calculated:

* **Creep**: Concrete creep using code formulas (CEB-FIP, ACI, etc.)
* **Shrinkage**: Age-dependent shrinkage strains
* **PT Relaxation**: Prestressing steel relaxation over time
* **PT Losses**: Elastic shortening and other prestress losses

#### XML Examples

**Simple 3-Stage Construction:**

```xml
<!-- Stage 1: Erect girders -->
<O T="ConstructionStage" N="Stage 1: Girders">
  <P N="AnalysisID" V="STAGE_1"/>
  <P N="Day" V="1"/>  <!-- Day 1 -->
  <P N="Temperature" V="70"/>
  <P N="Humidity" V="75"/>
  <P N="Creep" V="1"/>
  <P N="Shrinkage" V="1"/>

  <!-- Activate girders -->
  <O T="StructureState" N="Girders_Active">
    <P N="Group" V="@Girder_Group|FEGroup"/>
    <P N="Stiffness" V="1"/>  <!-- Activate -->
  </O>

  <!-- Apply girder self-weight -->
  <O T="ConstructionStageLoading">
    <P N="Case" V="@Girder_SelfWeight|AnalysisCase"/>
    <P N="Factor" V="1.0"/>
  </O>
</O>

<!-- Stage 2: Cast deck (28 days later) -->
<O T="ConstructionStage" N="Stage 2: Deck">
  <P N="AnalysisID" V="STAGE_2"/>
  <P N="ParentStage" V="@Stage 1: Girders|ConstructionStage"/>
  <P N="Day" V="28"/>  <!-- 28 days after Stage 1 -->
  <P N="Temperature" V="70"/>
  <P N="Humidity" V="75"/>
  <P N="Creep" V="1"/>
  <P N="Shrinkage" V="1"/>

  <!-- Activate deck -->
  <O T="StructureState" N="Deck_Active">
    <P N="Group" V="@Deck_Group|FEGroup"/>
    <P N="Stiffness" V="1"/>
  </O>

  <!-- Apply deck weight -->
  <O T="ConstructionStageLoading">
    <P N="Case" V="@Deck_SelfWeight|AnalysisCase"/>
    <P N="Factor" V="1.0"/>
  </O>
</O>

<!-- Stage 3: Prestressing (7 days after deck) -->
<O T="ConstructionStage" N="Stage 3: PT">
  <P N="AnalysisID" V="STAGE_3"/>
  <P N="ParentStage" V="@Stage 2: Deck|ConstructionStage"/>
  <P N="Day" V="7"/>
  <P N="Relaxation" V="1"/>  <!-- Include PT relaxation -->
  <P N="PTLoss" V="1"/>

  <!-- Apply prestressing -->
  <O T="ConstructionStageLoading">
    <P N="Case" V="@Prestress_Load|AnalysisCase"/>
    <P N="Factor" V="1.0"/>
  </O>
</O>
```

**Staged Construction with Element Removal:**

```xml
<O T="ConstructionStage" N="Stage: Remove Falsework">
  <P N="ParentStage" V="@Stage 2: Deck|ConstructionStage"/>
  <P N="Day" V="14"/>

  <!-- Deactivate falsework -->
  <O T="StructureState" N="Falsework_Removed">
    <P N="Group" V="@Falsework_Group|FEGroup"/>
    <P N="Stiffness" V="0"/>  <!-- Deactivate -->
  </O>
</O>
```

**Output:**

* Cumulative displacements at each stage
* Time-dependent deformations (creep, shrinkage)
* PT losses over time
* Element forces at each construction stage

***

## Materials and Sections

### 1. Material References

Materials defined in MAT module, referenced by FE elements.

**Module:** `MAT.Material`

**Key Properties:**

* Young's modulus (E)
* Poisson's ratio (Nu)
* Shear modulus (G)
* Density
* Thermal expansion coefficient

**Reference in Elements:**

Material is typically assigned through the Section, not directly on FELine. However, you can override material properties:

```xml
<O T="FELine" N="Beam1">
  <P N="Sec" V="@W24x76|SEC.Section" T="Section"/>  <!-- Section includes Material -->
  <!-- Optional: override material properties -->
  <P N="PropMatE" V="29000"/>  <!-- ksi -->
  <P N="PropMatNu" V="0.3"/>
</O>
```

***

### 2. Section References

Cross-sections defined in SEC module for beam elements.

**Module:** `SEC.Section`

**Key Properties:**

* Area (A)
* Moments of inertia (Ix, Iy, Iz)
* Torsional constant (J)
* Section moduli
* Width property (for distributed loads)

**Reference in FELine:**

```xml
<O T="FELine" N="Girder1">
  <P N="Sec" V="@W36x150|SEC.Section"/>
  <!-- For tapered members -->
  <P N="Sec2" V="@W36x210|SEC.Section"/>
</O>
```

***

## Analysis Results

After running FEA analyses, results must be extracted and organized for design checks and reporting.

**Result Types Available:**

* **Nodal displacements**: Translations (Tx, Ty, Tz) and rotations (Rx, Ry, Rz)
* **Nodal reactions**: Support forces and moments
* **Element forces**: Axial, shear, moment, torque for beam elements
* **Element stresses**: For shell and solid elements
* **Modal data**: Natural frequencies and mode shapes (eigenvalue analysis)

**Result Extraction:**

Results are extracted using ParamML functions within expressions. For comprehensive information on extracting and organizing FEA results, refer to the **AI-FEA-Results-Guide.md**.

**Common Result Functions:**

* `force(element, loadCase, component, station?)` - Extract specific force component
* `forcePos(component, element, loadCase, station?)` - Extract maximum force value
* `forceNeg(component, element, loadCase, station?)` - Extract minimum force value
* `stress(loadCase, element, station?)` - Extract stress components
* `disp(node, loadCase, component)` - Extract nodal displacement

**See AI-FEA-Results-Guide.md for:**

* Complete result extraction function reference
* Multi-station extraction patterns
* Limit state organization
* Concurrent force extraction
* Envelope and governing results
* Result data structures and indexing

***

## Advanced FEA Objects

### 1. Tendon (Prestressing)

Prestressed tendon definition and loading.

**Object Type:** `Tendon`

**Related Objects:**

* `TendonLoad`: Prestress force application
* `TendonPathPoint`: Tendon geometry control points

**Properties:**

* Path geometry (control points)
* Prestress force
* Jacking stress
* Duct diameter
* Friction coefficients

***

### 2. LiveLoadSurface

Define vehicle travel paths for live load analysis.

**Object Type:** `LiveLoadSurface`

**Related:**

* `AnalysisCaseLive`: Live load analysis configuration
* `DesignLane`: Traffic lane definitions
* Vehicle libraries (AASHTO trucks, etc.)

**Properties:**

* Surface boundary
* Travel direction
* Lane configurations
* Vehicle placement rules

***

## Complete XML Examples

### Example 1: Simple Beam Model

```xml
<!-- Nodes -->
<O T="Node" N="NODE_1" X="0" Y="0" Z="0"
   Tx="1" Ty="1" Tz="1" Rx="0" Ry="0" Rz="0"/>  <!-- Pinned support -->

<O T="Node" N="NODE_2" X="240" Y="0" Z="0"
   Tx="0" Ty="1" Tz="1" Rx="0" Ry="0" Rz="0"/>  <!-- Roller support -->

<!-- Beam element -->
<O T="FELine" N="BEAM_1">
  <P N="Node1" V="@NODE_1|Node" T="Node"/>
  <P N="Node2" V="@NODE_2|Node" T="Node"/>
  <P N="FEType" V="0"/>  <!-- BEAM -->
  <P N="Sec" V="@W24x76|SEC.Section" T="Section"/>
</O>

<!-- Dead load case -->
<O T="AnalysisCase" N="Dead Load">
  <P N="AnalysisID" V="DL"/>
  <P N="LoadType" V="DL"/>
  <P N="Active" V="1"/>
</O>

<!-- Point load at midspan -->
<O T="NodeLoad" N="MidspanLoad">
  <P N="LC" V="@Dead Load|AnalysisCase" T="AnalysisCase"/>
  <P N="Node" V="@NODE_1|Node" T="Node"/>
  <P N="Fz" V="-10000"/>  <!-- 10 kip downward -->
</O>
```

### Example 2: Shell Structure (Slab)

```xml
<!-- Node grid (4x4 = 16 nodes) -->
<O T="Repeat" N="NodeRows" S="0" E="3" I="1" CTRL="i" i="0">
  <O T="Repeat" N="NodeCols" S="0" E="3" I="1" CTRL="j" j="0">
    <O T="Node" N="NODE" X="j*120" Y="i*120" Z="0">
      <!-- Boundary conditions on edges -->
      <P N="Tz" V="(i==0 || i==3 || j==0 || j==3) ? 1 : 0"/>
    </O>
  </O>
</O>

<!-- Shell elements (3x3 = 9 elements) -->
<O T="Repeat" N="ShellRows" S="0" E="2" I="1" CTRL="i" i="0">
  <O T="Repeat" N="ShellCols" S="0" E="2" I="1" CTRL="j" j="0">
    <O T="FESurfMITC4" N="SHELL">
      <P N="Node1" V="@NODE_{i}_{j}|Node" T="Node"/>
      <P N="Node2" V="@NODE_{i}_{j+1}|Node" T="Node"/>
      <P N="Node3" V="@NODE_{i+1}_{j+1}|Node" T="Node"/>
      <P N="Node4" V="@NODE_{i+1}_{j}|Node" T="Node"/>
      <P N="Thickness" V="8"/>  <!-- 8 inch slab -->
      <P N="Mat" V="@Concrete_4ksi|MAT.Material" T="Material"/>
    </O>
  </O>
</O>

<!-- Surface load -->
<O T="AnalysisCase" N="Dead Load">
  <P N="AnalysisID" V="DL"/>
  <P N="LoadType" V="DL"/>
</O>

<!-- Uniform pressure (would need SurfaceLoad object, simplified here) -->
```

### Example 3: Complete Bridge Girder Analysis

```xml
<!-- Material -->
<O T="MAT.Material" N="Steel_A992">
  <P N="E" V="29000"/>  <!-- ksi -->
  <P N="Nu" V="0.3"/>
  <P N="Density" V="0.490"/>  <!-- kip/ft³ -->
</O>

<!-- Section -->
<O T="SEC.Section" N="W36x150">
  <!-- Section properties would be defined here -->
</O>

<!-- Groups -->
<O T="FEGroup" N="All_Structure"/>

<!-- Nodes along girder -->
<O T="Repeat" N="GirderNodes" S="0" E="10" I="1" CTRL="i" i="0">
  <O T="Node" N="NODE" X="i*12" Y="0" Z="0">
    <P N="Group" V="@All_Structure|FEGroup" T="FEGroup"/>
    <!-- End supports -->
    <P N="Tx" V="i==0 ? 1 : 0"/>
    <P N="Ty" V="(i==0 || i==10) ? 1 : 0"/>
    <P N="Tz" V="(i==0 || i==10) ? 1 : 0"/>
  </O>
</O>

<!-- Beam elements -->
<O T="Repeat" N="GirderElements" S="0" E="9" I="1" CTRL="i" i="0">
  <O T="FELine" N="BEAM">
    <P N="Node1" V="@NODE_{i}|Node" T="Node"/>
    <P N="Node2" V="@NODE_{i+1}|Node" T="Node"/>
    <P N="Sec" V="@W36x150|SEC.Section" T="Section"/>
    <P N="Group" V="@All_Structure|FEGroup" T="FEGroup"/>
  </O>
</O>

<!-- Load cases -->
<O T="AnalysisCase" N="Dead Load">
  <P N="AnalysisID" V="DL"/>
  <P N="LoadType" V="DL"/>
  <P N="ActiveGroup" V="@All_Structure|FEGroup"/>
</O>

<O T="AnalysisCase" N="Live Load">
  <P N="AnalysisID" V="LL"/>
  <P N="LoadType" V="LL"/>
  <P N="ActiveGroup" V="@All_Structure|FEGroup"/>
</O>

<!-- Uniform load on all nodes -->
<O T="Repeat" N="DeadLoads" S="1" E="9" I="1" CTRL="i" i="1">
  <O T="NodeLoad" N="DL">
    <P N="LC" V="@Dead Load|AnalysisCase" T="AnalysisCase"/>
    <P N="Node" V="@NODE_{i}|Node" T="Node"/>
    <P N="Fz" V="-2.5"/>  <!-- kip/ft * 12 ft = 30 kip total -->
  </O>
</O>

<!-- Load combination -->
<O T="Combination" N="Service_I">
  <O T="CombinationItem">
    <P N="Case" V="@Dead Load|AnalysisCase"/>
    <P N="Factor" V="1.0"/>
  </O>
  <O T="CombinationItem">
    <P N="Case" V="@Live Load|AnalysisCase"/>
    <P N="Factor" V="1.0"/>
  </O>
</O>

<!-- Modal analysis -->
<O T="AnalysisCaseEigen" N="Modal">
  <P N="AnalysisID" V="MODAL"/>
  <P N="Modes" V="6"/>
  <P N="Gravity" V="386.088583"/>
  <P N="SelfMassFactor" V="1.0"/>
  <P N="MassCase1" V="@Dead Load|AnalysisCase"/>
  <P N="MassCaseFactor1" V="1.0"/>
  <P N="ActiveGroup" V="@All_Structure|FEGroup"/>
</O>
```

***

## Best Practices

### 1. Constraint Encoding Conventions

Always use consistent constraint encoding:

* **0 or -1**: Free DOF
* **1**: Fixed DOF
* **Positive value**: Spring stiffness in consistent units

### 2. Group Organization

Organize elements into logical groups:

* By structural component (girders, deck, substructure)
* By material (steel, concrete)
* By construction stage (existing, new)
* Use hierarchical groups for complex structures

### 3. Load Case Naming

Use descriptive, consistent names:

* Include load type: `DL_`, `LL_`, `WS_`, etc.
* Include location/direction: `DL_Girders`, `LL_Lane1`
* Number sequentially: `DL_1`, `DL_2`

### 4. Analysis Type Selection

Choose appropriate analysis:

* **Static Linear**: Most common, elastic behavior
* **Modal**: Natural frequencies, dynamic properties
* **Response Spectrum**: Seismic analysis
* **Pushover**: Seismic performance, capacity curves
* **Staged Construction**: Bridges built in phases, time-dependent effects

### 5. Mesh Quality

For automatic meshing:

* Use aspect ratios < 4:1 for shells
* Avoid highly skewed elements
* Refine mesh in high-stress areas
* Check mesh connectivity before analysis

### 6. Nonlinear Solver Tuning

For nonlinear analysis:

* Start with small load increments
* Use displacement control for softening behavior
* Set appropriate tolerances (0.001 typical)
* Increase max iterations for complex problems (50-100)

### 7. Modal Analysis Mass Sources

Properly define mass:

* Include self-weight (SelfMassFactor = 1.0)
* Add sustained loads (MassCase with appropriate factors)
* Use NodeMass for concentrated masses
* Typical live load mass factor: 0.25-0.33

### 8. Time-Dependent Analysis

For staged construction:

* Define realistic stage durations (Day property)
* Set environmental conditions (Temperature, Humidity)
* Enable appropriate effects (Creep, Shrinkage, Relaxation)
* Use code-based formulas (TimeDepModal)

### 9. Reference Patterns

Use consistent object references:

* Always use the format: `V="@ObjectName|ObjectType"`
* For P element references, add `T="ObjectType"` attribute
* Example inline: `Node1="@NODE_1|Node"`
* Example P element: `<P N="Node1" V="@NODE_1|Node" T="Node"/>`

### 10. Unit Consistency

Maintain unit consistency throughout model:

* Force: kip, kN, or lb
* Length: in, ft, m, or mm
* Stress: ksi, MPa, or psi
* Gravity: 386.088583 in/s², 32.174 ft/s², 9.81 m/s²

***

## Common Patterns

### 1. Constraint Value Encoding

```
-1 or 0  →  Free DOF
1        →  Fixed DOF
> 1      →  Spring with stiffness value
```

### 2. Reference Patterns

Objects reference each other using the `@ObjectName|ObjectType` syntax:

```xml
<!-- Parameter-style reference (with T attribute for type) -->
<P N="Node1" V="@NODE_1|Node" T="Node"/>

<!-- Attribute-style reference (inline, more concise) -->
<O T="FELine" Node1="@NODE_1|Node" Node2="@NODE_2|Node"/>
```

### 3. Mesh Connectivity Indexing

Mesh arrays use **0-based indexing**:

```typescript
nodes: [[x1,y1,z1], [x2,y2,z2], ...]  // Index 0, 1, 2, ...
quads: [[0,1,5,4], [1,2,6,5], ...]   // References to node indices
```

### 4. Load Combination Envelope

```xml
<O T="Combination" N="Envelope_Max">
  <P N="Envelope" V="1"/>  <!-- Max envelope -->
  <O T="CombinationItem" Case="@LC1" Factor="1.25"/>
  <O T="CombinationItem" Case="@LC2" Factor="1.75"/>
  <O T="CombinationItem" Case="@LC3" Factor="0.5"/>
</O>
```

***

## Debugging Tips

### 1. Check Node Connectivity

Verify all elements reference valid nodes:

* Check node names match exactly (case-sensitive)
* Ensure nodes exist before elements reference them
* Verify Node1 ≠ Node2 for beam/spring elements

### 2. Verify Constraint Definitions

Check boundary conditions:

* At least 3 DOF must be constrained to prevent rigid body motion
* For 2D problems: constrain Tx, Ty, Rz (minimum)
* For 3D problems: constrain all 6 DOF at one node (minimum)
* Check for over-constrained systems (warnings)

### 3. Inspect Mesh Quality

Before analysis:

* Visualize mesh to check connectivity
* Look for duplicate nodes (coincident but separate)
* Check element normals (all pointing same direction for shells)
* Verify element aspect ratios

### 4. Troubleshoot Convergence

If nonlinear analysis fails to converge:

* Reduce load increment
* Increase max iterations
* Check for mechanism (insufficient constraints)
* Look for material/geometric nonlinearity issues
* Use displacement control instead of force control

### 5. Modal Participation Factors

After eigenvalue analysis:

* Check cumulative mass participation (should reach 90%+ in each direction)
* If low participation: extract more modes
* Verify mass sources (self-weight, mass cases, nodal masses)
* Check for missing mass (verify all elements have density/mass)

### 6. Time-Dependent Analysis Validation

For staged construction:

* Verify stage sequence (Day values increasing)
* Check ParentStage references
* Validate element activation/deactivation
* Compare results to hand calculations for simple cases
* Monitor PT losses over time

### 7. Result Extraction

If results appear incorrect:

* Verify correct AnalysisID in result keys
* Check unit system consistency
* Confirm load case is Active
* Inspect convergence (check analysis log)
* Validate coordinate system (Global vs Local results)

### 8. Spring/Gap Elements

For spring and gap elements:

* Verify stiffness values are reasonable (not too large or small)
* Check gap distances (positive = initial gap)
* For compression-only: use high stiffness + gap
* For tension-only: use TENSTRUSS element type

### 9. Response Spectrum Analysis

If RSA results unexpected:

* Check spectrum curve units (period vs frequency)
* Verify direction scale factors (Scale1, Scale2, Scale3)
* Confirm modal combination method (CQC for closely-spaced modes)
* Check damping ratio (typical: 0.05)
* Ensure enough modes extracted (90% mass participation)

### 10. Load Combinations

For combination issues:

* Verify all referenced load cases exist and are Active
* Check factors (negative for reversal)
* Confirm load cases have completed successfully
* Check envelope type (max, min, abs max)

***

## Summary

The OpenBrIM FEA system provides comprehensive analysis capabilities for bridge engineering:

**Core Objects:**

* **Nodes** (Node) with 6 DOF and flexible boundary conditions
* **Elements** (FELine, FESurface, FESpring) for beam, shell, and spring elements
* **Groups** (FEGroup) for organization and filtering
* **Loads** (NodeLoad, PointLoad, etc.) with multiple application methods

**Analysis Types:**

* **Static Linear**: Basic elastic analysis
* **Eigenvalue/Modal**: Natural frequencies and mode shapes
* **Response Spectrum**: Seismic analysis with spectrum curves
* **Pushover**: Nonlinear static performance evaluation
* **Staged Construction**: Multi-phase construction with time-dependent effects

**Key Features:**

* Parametric integration via ParamML expressions
* Automatic mesh generation
* Hierarchical grouping and filtering
* Comprehensive material and section libraries
* Advanced prestressing support

**Best Practices:**

* Use consistent constraint encoding (-1/0=free, 1=fixed, +value=spring)
* Organize elements into logical groups
* Properly define mass sources for dynamic analysis
* Set appropriate solver tolerances for nonlinear problems
* Verify mesh quality and connectivity before analysis

By following this guide, AI agents can create sophisticated finite element models for bridge analysis, leveraging the full power of the OpenBrIM parametric FEA system.