`) when you want child objects to override them
* Named Export groups can be overridden using `Override="1"` in extended objects:
```xml
```
4. **⚠️ CRITICAL: Never Add Guard Directly to T="Export" Objects**:
**Problem:** When `Guard` is added directly to `T="Export"` objects in library objects, the Guard appears on the library object instance in the source code, which can cause the entire object to not execute.
```xml
```
**Solution:** Add Guard to a nested Group within the Export object:
```xml
```
**Rule:** Always wrap guarded parameters in a nested `T="Group"` within the Export object.
**For more details:** See `AI-Export.md`
***
#### 1.3 DesignRun Objects
DesignRun objects are **bridge objects** that override parameters of a target library object specified by `LibObjTypeName`. They work similarly to `Extends` + `Override="1"`, but with a critical restriction: **only parameters that exist within the `LibObjTypeName` object can be overridden** (scoped override, not hierarchical).
**Purpose:**
* Override parameters of a specific library object (scoped to that object only)
* Act as a bridge between user-defined parameters and library object parameters
* Execute design calculations with custom parameter values
**Key Parameters:**
* **`LibObjTypeName`** (CRITICAL): Specifies which library object's parameters to override
* **`LibObjVersion`**: Version number of the target library object
**Key Restrictions:**
1. **Parameters only** - Cannot override child objects (cannot use `Override="1"` on objects)
2. **Must pre-exist** - Can only override parameters that already exist within `LibObjTypeName` scope
3. **Scoped to `LibObjTypeName`** - Overrides parameters within that library object and its extended objects
4. **Includes extended objects** - If `LibObjTypeName` has child objects using `Extends`, their parameters can also be overridden
**Common Practice:**
* **Typically override `Role="Input"` parameters** - These are data inputs from users
* **Rarely override calculated parameters** - If logic needs changing, modify the base library object instead
* **Rationale:** DesignRun is for **data override**, not **logic override**
**DesignRun Object Structure:**
```xml
```
**How DesignRun Works:**
```
┌─────────────────┐
│ User Parameters │ (e.g., UserWidth = 15)
└────────┬────────┘
│
▼
┌─────────────────┐
│ DesignRun │ OVERRIDES library parameters
│ T="DesignRun" │ width_input = UserWidth
└────────┬────────┘
│
▼
┌─────────────────┐
│ Library Object │ (MyCodeCheck)
│ (LibObjTypeName)│ Uses overridden: width_input
└─────────────────┘
```
1. **DesignRun** specifies target library object via `LibObjTypeName`
2. **Parameters in DesignRun** override corresponding parameters **within that library object's scope**
3. **Extended objects included** - Parameters from objects extended within `LibObjTypeName` can also be overridden
4. **If the same parameter name appears multiple times** in the library scope, **all instances are overridden**
5. **Library object** uses the overridden parameter values in its calculations
6. **Only parameters that exist in `LibObjTypeName` scope** can be overridden (no new parameters)
**CRITICAL: Bidirectional Parameter Synchronization**
DesignRun overrides are **scoped to the `LibObjTypeName` object only** (unlike `Extends` + `Override="1"` which is hierarchical). This means **parameter names must match** between the library object and DesignRun. When you rename a parameter:
**Direction 1: Library → DesignRun** If you rename a parameter in the library object that is overridden by DesignRun:
1. Find all DesignRun objects with `LibObjTypeName` pointing to that library
2. Update the parameter name in those DesignRun objects
**Direction 2: DesignRun → Library** If you rename a parameter in DesignRun that overrides a library parameter:
1. Check the library object specified in `LibObjTypeName`
2. Update the parameter name in that library object
3. Update all internal references to that parameter in the library
**Example 1: Scoped Override (Only LibObjTypeName)**
```xml
```
**Example 2: Overriding Extended Object Parameters**
```xml
```
**Example 3: Renaming Parameters**
```xml
```
**Step-by-Step: Renaming Parameters**
When you need to rename a parameter that's involved in DesignRun override:
**Starting from Library Object:**
1. **Identify the library object** (e.g., `OBPBase_MyCodeCheck`)
2. **Change the parameter name** in the library object (e.g., `oldName` → `newName`)
3. **Update all internal references** to that parameter within the library
4. **Search for all DesignRun objects** with `LibObjTypeName = "OBPBase_MyCodeCheck"`
5. **Update parameter names** in those DesignRun objects to match the new name
**Starting from DesignRun Object:**
1. **Find `LibObjTypeName`** value to identify the target library object
2. **Change the parameter name** in DesignRun (e.g., `oldName` → `newName`)
3. **Open the library object** specified in `LibObjTypeName`
4. **Update the parameter name** in the library object
5. **Update all internal references** to that parameter within the library
**⚠️ WARNING: Non-Input Parameter Override Behavior**
DesignRun has a **dangerous capability** that must be carefully controlled:
**The Problem:** DesignRun can override **ANY parameter** in the `LibObjTypeName` scope, not just `Role="Input"` parameters. When you override a non-Input parameter:
* **ALL occurrences** of that parameter name in the library object scope are overridden
* This includes uses in calculations, expressions, and child objects
* The override affects the entire `LibObjTypeName` object and its extended objects
**Example - Unintended Override:**
```xml
```
**Result:**
* `width_input` = 15 (from UserWidth) ✅ Expected
* `safety_factor` = 2.0 (from UserSafetyFactor) ⚠️ Overridden everywhere
* `capacity` = (15 \* 20) \* 2.0 = 600 (uses overridden safety\_factor)
* `check1` = 600 \* 2.0 = 1200 (uses overridden safety\_factor)
* `check2` = 15 \* 2.0 = 30 (uses overridden safety\_factor)
**When This Happens:**
* ❌ **Breaks library object's internal logic** - calculated parameters no longer use intended values
* ❌ **Creates maintenance nightmare** - changes to library don't behave as expected
* ❌ **Violates separation of concerns** - DR should only provide input data, not override calculations
* ❌ **Hard to debug** - override affects multiple locations silently
* ❌ **Unexpected behavior** - other developers don't expect internal parameters to be overridden
**What To Do Instead:**
**If user needs to control a parameter that's not `Role="Input"`:**
1. **Add `Role="Input"` to that parameter in the library object** (RECOMMENDED)
```xml
```
* Makes it officially part of the library object's API
* Clear to all developers that this parameter is meant to be configurable
* Proper design pattern - data inputs belong in `Role="Input"`
2. **If parameter should remain internal:**
* Do NOT override it from DesignRun
* Modify library object logic if behavior needs to change
* Keep data override (DR) separate from logic (library)
**Comparison:**
| Aspect | `Role="Input"` Parameter | Non-Input Parameter |
| ----------------------- | ---------------------------- | ----------------------------- |
| **Purpose** | User-configurable data input | Internal constant/calculation |
| **Recommended for DR?** | ✅ **YES** - primary use case | ❌ **NO** - problematic |
| **Override behavior** | Standard, expected | Overrides ALL occurrences |
| **Best practice** | Always map these in DR | NEVER override from DR |
| **User expectation** | Should be controllable | Should be internal/fixed |
| **When found in DR** | Normal, correct usage | Flag as error in code review |
**Best Practices:**
1. **Parameters only, not objects** - DesignRun can only override parameters, not child objects
2. **Must pre-exist in library scope** - Cannot add new parameters; can only override existing ones (including extended objects)
3. **Scoped to `LibObjTypeName`** - Overrides parameters within library object and its extended objects
4. **Extended objects included** - Parameters from `Extends` objects within library can be overridden
5. **ONLY override `Role="Input"` parameters** - These are data inputs designed to be overridden
6. **NEVER override non-Input parameters** - This breaks library logic and creates bugs
* ⚠️ If you find a non-Input override in DR: **Add `Role="Input"` to library or remove from DR**
7. **Multiple same-name parameters** - If the library has the same parameter name multiple times, **all are overridden**
8. **Data override, not logic override** - Use DesignRun for data inputs, use library edits for logic changes
9. **Bidirectional sync is critical** - Changes in either location require updates in the other
10. **Always check `LibObjTypeName`** to find which library object is being overridden
11. **Check extended objects too** - If library uses `Extends`, those parameters can also be overridden
12. **Search across multiple files** - DesignRun objects may be in different files than the library
13. **Test after renaming** to ensure overrides still work correctly
14. **Code review must flag non-Input overrides** - These are bugs that need fixing
### 2. Parameters (`Param`)
Parameters store data and expressions within objects. They are the "DNA" of parametric behavior.
**Parameter Types:**
* **Number** (`ParamType.Number`): Numeric values or mathematical expressions
* **Text** (`ParamType.Text`): String values or object references
**Value Types:**
* **Expression** (`ValueType.Expression`): Contains formulas that are evaluated (e.g., `"L/2 + 10"`)
* **Value** (`ValueType.Value`): Contains literal values (e.g., `100`)
**Parameter Properties:**
* `Name` (`N`): Parameter identifier
* `Value` (`V`): The expression or value
* `Type` (`T`): Expr, Num, Text, or ObjectType (for references)
* `Description` (`D`): Human-readable description
* `UnitType` (`UT`): Length, Force, Stress, etc.
* `UnitCategory` (`UC`): Default, Metric, Imperial, etc.
* `Role`: None, Input, Private, Export, Import
* `Category`: For grouping parameters in UI
* `DisplayWidth`: UI display width
* `Attr`: If "1", parameter is serialized as XML attribute (for brevity)
* `Optional`: If "1", parameter is optional
### 3. Expression Evaluation (`Eval`)
The evaluation engine computes parameter values by:
1. **Parsing** expressions using JavaScript-compatible syntax
2. **Resolving** identifiers to their values from the parametric model
3. **Executing** mathematical operations and functions
4. **Caching** results for performance
**Supported Operations:**
* Arithmetic: `+`, `-`, `*`, `/`, `%`, `^`
* Comparison: `<`, `>`, `<=`, `>=`, `==`, `!=`
* Logical: `&&`, `||`, `!`
* Ternary: `condition ? value1 : value2`
* Mathematical functions: `sqrt`, `abs`, `sin`, `cos`, `tan`, `asin`, `acos`, `atan`, `atan2`, `min`, `max`, `pow`, `exp`, `log`, `floor`, `ceil`, `round`, etc.
**Identifier Resolution:**
* Parameters are referenced by name (e.g., `Length`, `Width`)
* The system uses a distance-based algorithm to resolve identifiers (detailed below)
* Objects are referenced by name and accessed with dot notation (e.g., `Girder1.Length`)
* Use brackets for indexed access (e.g., `Girders[0].Width`)
#### 3.1 Lazy Evaluation
The parametric engine uses **lazy evaluation**, meaning expressions are not computed when they are defined—they are evaluated only when their values are actually needed.
**How It Works:**
1. **Definition Time**: Expressions are stored as text strings and compiled into an Abstract Syntax Tree (AST)
2. **Evaluation Time**: When a parameter value is requested (e.g., for display, geometry generation, or use in another expression), the `GetValue()` method is called
3. **Backward Evaluation**: The engine works backward through dependencies—if ParamA needs ParamB, it evaluates ParamB first, which might need ParamC, and so on
4. **Caching**: Computed values are cached to avoid redundant calculations. The cache is invalidated when dependencies change
5. **Circular Dependency Detection**: The execution stack tracks the evaluation chain to detect and prevent circular dependencies
**Benefits:**
* **Performance**: Only computes what's actually needed
* **Flexibility**: Parameters can reference objects/parameters that are defined later in the XML
* **Dynamic Updates**: When an input parameter changes, only affected downstream parameters are re-evaluated on next access
**Example:**
```xml
```
**Evaluation Chain Example:**
```xml
```
#### 3.2 Distance-Based Parameter Resolution
When multiple parameters or objects have the same name, the engine uses a **distance-based algorithm** to determine which one to use. This allows parameters to be overridden at different levels of the hierarchy.
**Resolution Algorithm:**
When an expression references an identifier (e.g., `Width` or `Beam1`):
1. **Search Parent Chain First**: Walk up from current object to root, looking for the parameter
* Current object's parameters
* Parent's parameters
* Grandparent's parameters, etc.
* Stop if found or root is reached
2. **Search Entire Project** (if not found in parent chain): Get ALL parameters/objects with that name from the entire project
3. **Calculate Distance** for each candidate:
```
Distance = Steps through hierarchy + Scope Penalties
Where:
- Steps = number of parent→child hops from current object to candidate through their common ancestor
- Scope Penalty = +100 for EACH scope boundary crossed:
• Crossing into or out of an object with Scoped="1": +100
• Crossing into or out of a Private object: +100
```
4. **Pick Closest**: Select the parameter/object with the minimum distance
**Example: Basic Distance Resolution**
```xml
```
**Example: Parameter Shadowing (Override Pattern)**
```xml
```
**Example: Scope Penalty (+100 Distance)**
```xml
```
**Distance Calculation Reference:**
| Scenario | Steps | Penalties | Total Distance | Notes |
| ------------------------ | ------ | --------- | -------------- | ----------------------------- |
| Same object | 0 | 0 | **0** | Always wins |
| Parent object | 1 | 0 | **1** | |
| Grandparent | 2 | 0 | **2** | |
| Sibling (same parent) | 2 | 0 | **2** | Up 1, down 1 |
| Through scoped parent | 1 | +100 | **101** | Scope creates strong boundary |
| Sibling in scoped object | 2 | +100 | **102** | |
| Cross 2 scope boundaries | varies | +200 | **high** | Rarely wins |
| Uncle (parent's sibling) | 3 | 0 | **3** | Up 2, down 1 |
**Example: Nested Scopes**
```xml
```
### 4. Repeat/Iteration (`Repeat`)
The `Repeat` object enables parametric arrays and iterations.
**Key Parameters:**
* `CTRL`: Name of the control parameter (loop variable)
* ⚠️ **WARNING**: Do NOT use reserved keywords as CTRL names (e.g., `pi`, `e`, `sin`, `cos`, etc.)
* `pi` is reserved for π (3.14159...) and cannot be used as a loop variable
* Use descriptive names like `i`, `j`, `k`, `idx`, `pileIndex`, etc.
* `S`: Start value
* `E`: End value
* `I`: Increment (default: 1)
During compilation, the Repeat generates copies of its child content for each iteration.
**Example:** Create 5 points along a line
```xml
```
**For details** See `AI-Core-Objects.md`
## Guards - Conditional Object Activation
**Guard** is a special parameter that activates or deactivates objects based on conditions.
### Purpose
Guards allow conditional geometry, calculations, or object creation based on user selections or parameter values.
### Syntax
```xml
```
The Guard parameter must evaluate to a boolean (true/false):
* **True** → Object is active and evaluated
* **False** → Object is deactivated (skipped)
### Common Guard Operators
* `.EQ.` - Equal to
* `.NE.` - Not equal to
* `.GT.` - Greater than
* `.LT.` - Less than
* `.GE.` - Greater than or equal
* `.LE.` - Less than or equal
* `.AND.` - Logical AND
* `.OR.` - Logical OR
### Example: Conditional Column Geometry
```xml
```
**How it works:**
1. User selects `ColumnType` (Rectangular or Circular)
2. Each geometry object has a Guard checking the selection
3. Only the matching object is activated and creates geometry
4. The other object is skipped
### Multiple Conditions
Guards can use complex conditions:
```xml
```
### Common Patterns
**Option Selection:**
```xml
```
**Threshold-Based:**
```xml
```
**Multiple Criteria:**
```xml
```
***
## XML Format
### Basic Structure
```xml
...
```
### Concise vs. Verbose Format
**Concise (Preferred):** When possible, define parameters as attributes on the object node:
```xml
```
**Verbose:** When you need to specify parameter metadata (units, description, role, etc.):
```xml
```
### Common Patterns
#### 1. Simple Numeric Parameter
```xml
```
#### 2. Expression Parameter
```xml
```
#### 3. Parameter with Units
```xml
```
#### 4. Text Parameter
```xml
```
#### 5. Object Reference
```xml
```
#### 6. Object Reference (Attribute Style)
When defining as an attribute, prefix with `@` and optionally specify type with `|`:
```xml
```
#### 7. User Input Parameter
```xml
```
#### 8. List/Array Parameter
```xml
```
#### 9. Referencing Objects Pattern (Bidirectional References)
This pattern establishes automatic two-way references between parent and child objects. When a child object references a parent, it automatically appears in the parent's "Referencing Objects" list. This is essential for navigating object relationships in complex models.
**Use Cases:**
* Girder → Cross Frames (bracings)
* Pier Column → Foundation
* Deck → Barrier
**Parent Object (Girder):**
```xml
```
**Child Object (CrossFrame):**
```xml
```
**Key Components:**
| Component | Location | Purpose |
| ---------------------- | ------------------------------------ | --------------------------------------------------------- |
| `bracings` parameter | Parent's "Referencing Objects" group | Stores list of child objects |
| `ReadOnly="1"` | Parent's ParamInfo | Prevents manual editing, system-managed |
| `RefParam="@bracings"` | Child's ParamInfo | Tells system to add this object to parent's bracings list |
**How It Works:**
1. User creates child object (CrossFrame) and selects parent (Girder)
2. System automatically adds CrossFrame to Girder's `bracings` list via RefParam
3. Parent's "Referencing Objects" tab shows all children
4. When child is deleted, it's automatically removed from parent's list
**Navigation Through References:**
Other objects can navigate through referencing objects to access nested data. For example, a Deck object takes a girder list as input, then can access each girder's cross frames via `girder.bracings`:
```xml
```
#### 9. Referencing Objects Pattern (Bidirectional References)
This pattern establishes automatic two-way references between parent and child objects. When a child object references a parent, it automatically appears in the parent's "Referencing Objects" list. This is essential for navigating object relationships in complex models.
**Use Cases:**
* Girder → Cross Frames (bracings)
* Pier Column → Foundation
* Deck → Barrier
**Parent Object (Girder):**
```xml
```
**Child Object (CrossFrame):**
```xml
```
**Key Components:**
| Component | Location | Purpose |
| ---------------------- | ------------------------------------ | --------------------------------------------------------- |
| `bracings` parameter | Parent's "Referencing Objects" group | Stores list of child objects |
| `ReadOnly="1"` | Parent's ParamInfo | Prevents manual editing, system-managed |
| `RefParam="@bracings"` | Child's ParamInfo | Tells system to add this object to parent's bracings list |
**How It Works:**
1. User creates child object (CrossFrame) and selects parent (Girder)
2. System automatically adds CrossFrame to Girder's `bracings` list via RefParam
3. Parent's "Referencing Objects" tab shows all children
4. When child is deleted, it's automatically removed from parent's list
**Navigation Through References:**
Other objects can navigate through referencing objects to access nested data. For example, a Deck object takes a girder list as input, then can access each girder's cross frames via `girder.bracings`:
```xml
```
## Practical Examples
### Example 1: Simple Rectangle
```xml
```
### Example 2: Parametric Rectangle
```xml
```
### Example 3: Array of Points Using Repeat
```xml
```
### Example 4: Girder with Cross-Section
```xml
```
### Example 5: Multi-Girder Bridge
```xml
```
### Example 6: Conditional Objects (Guards)
```xml
```
### Example 7: Object Inheritance (Creating Variations)
```xml
```
## Advanced Features
### Object Inheritance
Objects can inherit from other objects in the project by using the base object's name as their `Type`. When you do this, the new object inherits all parameters and child objects from the base object, and you can override specific parameters as needed.
**Pattern:**
1. Define a base object with parameters
2. Create derived objects using the base object's name as the `T` attribute
3. Override parameters by specifying them as attributes or child parameters
**Example:**
```xml
```
In the above example, `SkinnyCol` and `WideCol` inherit all the parameters, child objects, and behavior from `Col`, but override the dimensional parameters. This is particularly useful for creating variations of standard components.
### Extends - Importing Library Objects
#### Overview
The `Extends` attribute copies all parameters and child objects from one or more library objects into your current object. This is the primary mechanism for:
* Importing AASHTO chapter implementations
* Reusing calculation modules
* Building complex objects from simpler components
* Creating object namespaces
**Key Concept:** Think of Extends as **copying the entire object tree** from the library object(s) into your object.
***
`Extends` creates a **new instance** (copy) of the library object. Think of the library as a **class/template**, and each `Extends` creates a **new object instance** from that template.
**Key Concept:** Each time you use `Extends`, you create a separate instance with its own copy of the library's code.
**Example - Creating Multiple Instances:**
```xml
```
**What Happens:**
1. **Extends creates a new instance**: `Extends="AASHTO_Section3_4::v3"` makes a complete copy of the library's structure into the new object
2. **Each Extends = Separate Instance**: Instance1 and Instance2 are independent copies with their own parameter values
3. **Override="1" enables parameter replacement**: Allows you to define parameters that **replace** same-named parameters in **this instance's copy**
4. **Original library unchanged**: The AASHTO\_Section3\_4 library itself remains unchanged
5. **Independent calculations**: Instance1 calculates with ADTTSL=5000, Instance2 with ADTTSL=8000
**Object-Oriented Programming Analogy:**
```javascript
// Library is like a class
class AASHTO_Section3_4 {
constructor(ADTTSL = 0, NumYears = 100) {
this.ADTTSL = ADTTSL;
this.NumYears = NumYears;
this.FatiqueI = { LL: 1.5 * (this.ADTTSL / this.NumYears) };
}
}
// Extends + Override = new instance with constructor parameters
let instance1 = new AASHTO_Section3_4(5000, 75); // Chapter3_4_Instance1
let instance2 = new AASHTO_Section3_4(8000, 100); // Chapter3_4_Instance2
// Access instance results
let loadFactor1 = instance1.FatiqueI.LL;
let loadFactor2 = instance2.FatiqueI.LL;
```
**Without Override (Reading Default Values):**
```xml
```
**With Override (Setting Instance Parameters):**
```xml
```
**Key Takeaways:**
* `Extends` = Create new instance (copy) from library template
* `Override="1"` = Enable replacing parameters and objects in this instance
* Each `Extends` creates a **separate, independent instance**
* Parameters/objects you define replace same-named parameters/objects in **that instance only**
* Original library remains unchanged
## **For more detailed explanation:** See `AI-Extends.md`
#### Overriding Objects (Not Just Parameters)
With `Override="1"`, you can override **child objects** by defining objects with the same name, not just parameters.
**Example - Overriding Child Objects:**
```xml
```
**How Override Works:**
1. The engine copies the library into the instance
2. For each parameter/object you define in the instance
3. It searches for a matching name in the copied library
4. If found, it **replaces** that parameter/object entirely
5. This works for both parameters (``) and objects (``)
**Use Cases:**
* Override specific calculation modules while keeping the rest of the library
* Replace default implementations with custom logic
* Inject test values for specific sub-objects
***
#### Multiple Extends
You can extend from multiple objects by using array syntax:
```xml
```
**Key Points:**
* Use array syntax: `Extends="[Obj1, Obj2, Obj3]"`
* All listed objects are copied into your object
* If objects have parameters with the same name, the last one in the list wins
* Transitive: If you extend A, and A extends B, you also get B's content
***
#### Override Attribute - Setting Library Inputs
Library objects often define input parameters (with `Role="Input"`). The `Override="1"` attribute allows you to provide values for these inputs when extending the library.
**Think of it Like a Function Call:**
```xml
```
**Conceptual Equivalent in Programming:**
```javascript
// Library is like a function
function AASHTO_Section4_6(Mmajbend, Ddepth, lunbr, Rrad) {
// Internal calculations
let M_lat = someComplexCalculation(Mmajbend, Ddepth, lunbr, Rrad);
return { SC4_6_1_2: { M_lat: M_lat } };
}
// Extending with Override is like calling the function
let ForCurvatureEffects_AbsMax = AASHTO_Section4_6(
Mmajbend: max(abs(MuStrPos), abs(MuStrNeg)),
Ddepth: dw_Input,
lunbr: Lb_Input,
Rrad: RadOfGird
);
// Access the result
let LateralMoment = ForCurvatureEffects_AbsMax.SC4_6_1_2.M_lat;
```
***
#### Scoped Attribute with Extends
The `Scoped="1"` attribute is commonly used with library imports to prevent parameter name conflicts.
**Without Scoped:**
```xml
```
**With Scoped:**
```xml
```
**Best Practice:** Always use `Scoped="1"` when importing library objects to avoid unintended parameter shadowing.
***
#### Versioning with ::v3
Library objects often include version tags (e.g., `::v3`) to support multiple versions of the same code.
```xml
```
**Benefits:**
* Backward compatibility - old projects keep using ::v3
* Gradual migration - test ::v4 in parallel
* Clear dependency tracking
***
#### Complete Real-World Example
```xml
```
***
#### Key Takeaways
1. **Extends = Copy**: Copies the entire object tree from library into your object
2. **Container Pattern**: Create `` for namespacing
3. **Override="1"**: Allows setting input parameters of the extended library object
4. **Scoped="1"**: Isolates library internals from your project namespace
5. **Dot Notation**: Access library content via `ContainerName.InternalPath.Parameter`
6. **Multiple Extends**: Use array syntax `Extends="[Obj1, Obj2, Obj3]"`
7. **Versioning**: Use `::v3` for version control
***
#### Common Patterns Summary
**Pattern 1: Import Library as Namespace**
```xml
```
**Pattern 2: Import Library with Input Override**
```xml
```
**Pattern 3: Extend Multiple Libraries**
```xml
```
**Pattern 4: Transitive Access**
```xml
```
***
### Station-Dependent Parameters
Some parameters can vary along a station (alignment coordinate):
```xml
```
Format: `[[station_start, station_end], value, ...]`
### Built-in Functions
Common parametric functions available in expressions:
* **Geometric:** `online(p1, p2, t)`, `intersect(line1, line2)`, `point(obj, station)`
* **Array:** `sum(array)`, `min(...)`, `max(...)`, `length(array)`, `first(array)`, `last(array)`
* **Units:** `convert(value, fromUnit, toUnit)`, `withunits(value, unitType, unitCat)`
* **Object queries:** `refs(objType)`, `objs(objType)`, `value(objName, paramName)`
* **Geometry:** `surfarea(surface)`, `volume(solid)`, `perimeter(boundary)`
### Special Identifiers
* `self`: Reference to current object
* `myself`: Reference to current parameter's parent object
* `pi`: π constant
* `NULL`: Null object reference
## Best Practices
### 1. Use Descriptive Names
```xml
```
### 2. Provide Default Values for Inputs
```xml
```
### 3. Use Appropriate Unit Types
```xml
```
### 4. Prefer Concise Format When Possible
```xml
```
### 5. Group Related Objects
```xml
```
### 6. Use Guards for Conditional Content
Choose the appropriate guard type for your use case:
* **Guard**: For typical optional components (most common)
* **GuardX**: For library development when you need to preserve the guard condition
* **DesignGuard**: For design checks that may not apply in all cases
```xml
```
### 7. Use map() for Parameter Loops, Repeat Only for Objects
**CRITICAL PERFORMANCE RULE:** Never use Repeat for calculating parameter values—always use functional programming instead.
```xml
```
**When to use each:**
* **Use Repeat**: Creating actual objects (Points, Lines, Volumes, Girders, etc.)
* **Use map()**: Transforming data, extracting properties, calculating values
* **Use filter()**: Selecting subset of data based on conditions
* **Use reduce()**: Aggregating data to single value
```xml
```
See section 4.1 for detailed explanation and performance impact.
### 8. Document Complex Expressions
```xml
```
### 8. Use Scoped Objects Deliberately
Use `Scoped="1"` to create isolated parameter namespaces and prevent accidental parameter resolution from outside:
```xml
```
### 9. Avoid Unintentional Parameter Shadowing
Be deliberate when using the same parameter name at multiple hierarchy levels. If shadowing is unintentional, use unique names:
```xml
```
### 10. Understand Distance-Based Resolution
When multiple parameters share the same name, document the expected resolution in comments:
```xml
```
### 11. Optimize for Lazy Evaluation
Structure your model to take advantage of lazy evaluation:
```xml
```
### 12. Consider Hierarchy Performance
Avoid excessively deep hierarchies for frequently-accessed parameters:
```xml
```
## Common Pitfalls to Avoid
1. **Using Repeat for Parameter Loops (CRITICAL PERFORMANCE ISSUE):** This is the #1 performance mistake in ParamML models.
**❌ WRONG:**
```xml
```
**Problem:** Creates 100 objects in project tree, slow compilation, high memory usage
**✅ CORRECT:**
```xml
```
**Why:** Single parameter, instant evaluation, minimal memory
**Rule:** Use Repeat ONLY to create objects that must exist in the 3D model, FEA mesh, or project tree. For all data transformations, use `map()`, `filter()`, or `reduce()`.
See section 4.1 for detailed explanation.
2. **Circular Dependencies:** Ensure Parameter A doesn't depend on Parameter B if B depends on A. The lazy evaluation system will detect this and throw an error.
3. **Undefined References:** Always ensure referenced objects/parameters exist in the hierarchy or project.
4. **Type Mismatches:** Don't use numeric expressions for Text parameters.
5. **Missing Units:** Specify unit types for physical quantities (Length, Force, Stress, etc.).
6. **Invalid Guards:** Guard expressions must evaluate to 0 (false) or 1 (true).
7. **Repeat Issues:** Ensure S, E, and I parameters create finite iterations.
8. **Unintended Parameter Shadowing:** When multiple parameters have the same name at different hierarchy levels, the closest one (by distance) is used. This can cause unexpected behavior if you're not aware of which parameter is being resolved.
```xml
```
9. **Scope Boundary Surprises:** Objects with `Scoped="1"` add +100 to distance calculations, creating strong isolation boundaries. Parameters inside scoped objects are "far away" from outside objects.
```xml
```
10. **Distance vs. XML Order Confusion:** Parameter resolution is based on **hierarchy distance**, not the order parameters appear in XML. The engine always picks the closest parameter by distance, even if another parameter with the same name was defined first.
11. **Lazy Evaluation Timing:** Remember that expressions are NOT evaluated when defined. They're evaluated on-demand. Changing an input parameter doesn't automatically update dependent parameters until they're accessed.
```xml
```
12. **Guard Expression Restrictions:** Guard/GuardX expressions cannot reference parameters inside the object they guard (this would create a circular dependency during compilation). Always reference external parameters for guard conditions.
```xml
```
Additionally, remember that Guard and GuardX are compile-time (object removed if false), while DesignGuard is runtime (object marked "not applicable" in reports).
13. **Deep Hierarchy Performance:** Extremely deep hierarchies (10+ levels) can slow down parameter resolution. Consider flattening the structure or using scoped objects strategically to limit search scope.
## Debugging Tips
1. **Check Parameter Names:** Names are case-sensitive.
2. **Verify Object Types:** Ensure `T` attribute matches actual class names.
3. **Test Expressions:** Start with simple literals before adding complexity.
4. **Use Descriptive Names:** Makes debugging much easier and reduces shadowing issues.
5. **Check Parent-Child Structure:** Ensure objects are properly nested.
6. **Validate XML:** Ensure proper closing tags and attribute quoting.
7. **Trace Parameter Resolution:** When a parameter has an unexpected value, manually calculate the distance from the evaluation point to all candidates with that name. The one with minimum distance wins.
```
Example: If "Width" evaluates to unexpected value:
1. Find all parameters/objects named "Width" in the project
2. For each, count steps from current object through common ancestor
3. Add +100 for each Scoped="1" boundary crossed
4. The one with lowest total distance is being used
```
8. **Check Scope Boundaries:** Look for `Scoped="1"` attributes in parent objects. They create isolation that may prevent expected parameter resolution.
9. **Verify Lazy Evaluation:** If a parameter doesn't seem updated after changing an input, check if anything has actually requested its value. Try explicitly accessing it to trigger re-evaluation.
10. **Use Unique Names Strategically:** If shadowing is causing confusion, use unique parameter names across the hierarchy, or use very deliberate shadowing for override patterns.
11. **Debug with Comments:** Add XML comments showing expected distance calculations to document your resolution assumptions:
```xml
```
## Advanced Library Development Features
The following features are essential for creating reusable library components with rich UI integration and metadata.
### 1. ParamInfo Object
`ParamInfo` is a special object type that provides metadata and configuration for parameters, controlling their UI behavior, validation, and visibility.
**Common ParamInfo Attributes:**
* `Param`: Name of the parameter being configured (use `@` prefix for object references)
* `Required`: If "1", parameter must be provided (UI enforces)
* `Pick`: If "1", enables object picker UI for selection
* `List`: If "1", parameter is a list/array
* `Min`: Minimum number of list items
* `Max`: Maximum number of list items
* `ListColumnHeaders`: Array of column header names for list UI
* `ListColumnTypes`: Array of types for each column
* `ParamGuard`: Conditional visibility expression (see ParamGuard section below)
* `ParamInterface`: Custom parameter input interface (see ParamInterface section below)
**⚠️ CRITICAL: Min and Max for List Parameters**
When using `Pick="1"` with list parameters, **BOTH Min and Max must be specified** if you want to allow multiple selections. If only `Min` is provided without `Max`, the system defaults `Max` to 1, allowing only a single selection even if `Min > 1`.
```xml
```
**Rule:** For list inputs with unknown maximum count, always specify a reasonable `Max` value (e.g., `Max="100"`).
**Example: Required Object with Picker**
```xml
```
This makes the `Girder` parameter required and adds a UI picker button for selecting girder objects.
**Example: List Parameter with UI Configuration**
```xml
```
This configures `NonCompCase` as a list with 1-50 items and uses a custom interface for input.
**Example: List with Column Headers**
```xml
```
This creates a list parameter with a single column labeled "Additional Stations".
**Complete Example:**
```xml
```
### 2. Object Metadata Attributes
Library objects can include metadata attributes that control organization, categorization, and UI display.
**Metadata Attributes:**
* `Tags`: Comma-separated tags for filtering and categorization (prefix with `@` for tag names)
* `ObjLabel`: User-friendly display name for the object
* `Category`: Hierarchical category path (use `:` separator for subcategories)
**Example:**
```xml
```
**Tag Usage:**
* `@secondlayer`: Indicates this is a secondary-level component
* `@usastandard`: US design standards
* `@steelIGirder`: Applies to steel I-girder bridges
* `@release`: Ready for production release
**Category Hierarchy:** The category path creates a tree structure in the UI:
```
Code Check Objects
└─ Code Check Sub Objects
└─ Girder Stress Summary Table
```
**Best Practices:**
* Use descriptive `ObjLabel` values that users will recognize
* Create consistent tag vocabularies across your library
* Organize categories hierarchically from general to specific
* Use tags for filtering (e.g., bridge type, code standard, region)
### 3. Extends Attribute
The `Extends` attribute provides a different inheritance mechanism than the `T` (Type) attribute. While `T` specifies the object's class or base type, `Extends` allows you to inherit parameters and structure from another object while maintaining a different base type.
**Syntax:**
```xml
```
**Key Differences:**
* **Type (`T`)**: Defines the object's fundamental class (e.g., `Project`, `Group`, `Volume`)
* **Extends**: Imports parameters and child objects from another object without changing the base type
**Example:**
```xml
```
**Versioning Pattern:** Use `::vN` suffix for versioned objects to maintain backward compatibility:
```xml
...
...
...
```
**When to Use Extends vs Type:**
* Use **Type (`T`)**: To define what kind of object it is (Volume, Group, Project, etc.)
* Use **Extends**: To import a set of default parameters and structure from a template
### 4. ParamGuard
`ParamGuard` is different from `Guard` - while `Guard` removes entire objects, `ParamGuard` controls **parameter visibility** in the UI based on conditions.
**Key Differences:**
| Feature | Guard | ParamGuard |
| -------------- | ----------------------- | -------------------------------- |
| **Applied To** | Objects | Parameters (via ParamInfo) |
| **Effect** | Removes object if false | Hides parameter UI if false |
| **Evaluation** | Compile-time | Runtime (UI update) |
| **Use Case** | Conditional components | Conditional parameter visibility |
**Syntax:**
```xml
```
**Example: Conditional Parameter Visibility**
```xml
```
In this example:
* When `ReinfDataPref == 0`: Only `LumpedTopReinfArea` is visible in UI
* When `ReinfDataPref == 1`: `DetailedBarSize` and `DetailedBarSpacing` are visible
**Complex Conditions:**
```xml
```
**Best Practices:**
* Use ParamGuard to simplify UI by hiding irrelevant parameters
* Guard expressions should reference other parameters in the same object or parent objects
* Combine with `Required` flag: `Required="1"` only enforces when ParamGuard is true
* Keep guard expressions simple and fast (evaluated on every UI update)
### 5. ParamInterface
`ParamInterface` specifies a custom UI component for parameter input, enabling specialized editing experiences beyond standard text/number inputs.
**Syntax:**
```xml
```
**Common Custom Interfaces:**
* `@OBPParamInterfaceCombinationAndFactors`: Load combination editor
* `@OBPParamInterfaceStationPicker`: Station selection with alignment visualization
* `@OBPParamInterfaceColorPicker`: Color selection UI
* `@OBPParamInterfaceMaterialPicker`: Material database browser
**Example: Load Combination Interface**
```xml
```
**Example: Custom Table Interface**
```xml
```
**Creating Custom Interfaces:** Custom interfaces are defined as objects with specific UI behavior:
```xml
```
### 6. List Parameters with UI Configuration
List (array) parameters can be configured with rich UI metadata using ParamInfo.
**List Configuration Attributes:**
* `List="1"`: Declares parameter as a list
* `Min`: Minimum number of items (enforced by UI)
* `Max`: Maximum number of items
* `ListColumnHeaders`: Array of column names (as JSON array string)
* `ListColumnTypes`: Array of types for each column ('Number', 'Text', 'Object', etc.)
**Example: Simple List**
```xml
```
**Example: Multi-Column List**
```xml
```
**Example: List of Object References**
```xml
```
**Accessing List Items in Expressions:**
```xml
```
**Best Practices:**
* Always set reasonable `Min` and `Max` limits
* Provide descriptive column headers
* Match `ListColumnTypes` to actual data types for proper validation
* Use `Pick="1"` for lists of object references to enable picker UI
### 7. NAME\_ALIAS and EXPR\_ALIAS
These special documentation markers in parameter descriptions provide human-readable aliases for parameters and expressions, improving code readability and auto-generated documentation.
**Syntax in Description Field:**
```xml
```
**NAME\_ALIAS - Readable Parameter Names:**
```xml
```
When referenced in reports or UI:
* Shows "My\_Total" instead of "My\_Pos\_MaxF\_Total"
* Shows "Mx\_DL" instead of "Mx\_Neg\_DL\_Max"
**EXPR\_ALIAS - Readable Expressions:**
```xml
```
In documentation and error messages:
* Shows "σ/σ\_allowable" instead of the internal expression
* Shows "KL/r" instead of "EffectiveLength / RadiusOfGyration"
**Complete Example:**
```xml
```
**Benefits:**
* Auto-generated reports show clean, professional notation
* Error messages reference familiar names
* Code remains self-documenting
* Maintains backward compatibility (internal names unchanged)
**Best Practices:**
* Use NAME\_ALIAS for commonly referenced parameters
* Use EXPR\_ALIAS for mathematical expressions with standard notation (Greek letters, engineering symbols)
* Place aliases at the beginning of the description
* Keep aliases concise and meaningful
### 8. StaticParams on Repeat
`StaticParams` is a performance optimization attribute for `Repeat` objects that identifies parameters whose values don't change across iterations.
**Problem:** In a `Repeat` object, child objects are instantiated for each iteration. Normally, all parameters are re-evaluated for every iteration, even if they reference values that are constant across all iterations.
**Solution:** `StaticParams` tells the engine which parameters can be evaluated once and reused across all iterations.
**Syntax:**
```xml
```
**IMPORTANT:** The StaticParams value MUST be enclosed in square brackets `[]`. Without brackets, it will not work correctly.
```xml
...
...
```
**Example Without StaticParams (Inefficient):**
```xml
...
```
**Example With StaticParams (Optimized):**
```xml
...
```
**Real-World Example:**
```xml
```
**Performance Impact:**
* Without `StaticParams`: If repeating 100 times with 10 static parameters = 1,000 evaluations
* With `StaticParams`: 10 evaluations (static) + 100 evaluations (dynamic) = 110 evaluations
* **\~90% reduction in redundant calculations**
**Best Practices:**
* Include all parameters that reference parent objects or global constants
* Include material properties, design codes, and analysis settings
* Exclude parameters that use the iteration variable (`i`, `CTRL`)
* Exclude parameters that reference the current iteration's data
* Test with and without to verify performance improvement (significant for large repeats)
### 9. Section Geometry Objects
Section objects define cross-sectional geometry for structural elements. These are used for visualization, analysis, and design calculations.
**Core Section Objects:**
* `Section`: Container for cross-section definition
* `Shape`: Defines a 2D closed polygon within a section
* `Circle`: Defines a circular shape within a section
* `Point`: Vertices of shapes (2D local coordinates)
**Section Object Structure:**
```xml
```
**Example: I-Girder Section**
```xml
```
**Example: Rectangular Section with Circular Void**
```xml
```
**Circle Object Attributes:**
* `CX`: X-coordinate of center
* `CY`: Y-coordinate of center
* `R`: Radius
* `IsVoid`: If "1", circle is subtracted from section (void/opening)
**ComputeProp Attribute:**
* `ComputeProp="0"`: Section properties are NOT automatically computed (you provide them manually)
* `ComputeProp="1"`: Section properties (area, inertia, etc.) are automatically computed from geometry
**Section with Properties:**
```xml
...
```
**Using Sections in Structural Elements:**
```xml
```
**Station-Dependent Sections:**
```xml
```
### 10. Custom Object Types
Custom object types enable type-safe parameter references and ensure parameters reference objects of the correct type.
**Standard Type Attribute:**
```xml
```
**Custom Object Type:**
```xml
```
**Type Hierarchy Example:**
```xml
```
**Common Custom Types in OpenBrIM:**
* `OBPBase_GirderAnalysisResultsRef`: Reference to girder analysis results
* `OBPInsertionPoint`: Reference to an insertion point object
* `OBPSection`: Reference to a section definition
* `OBPLoadCase`: Reference to a load case
* `OBPCombination`: Reference to a load combination
* `MaterialSteel`: Reference to a steel material object
* `MaterialConcrete`: Reference to a concrete material object
**Benefits of Custom Types:**
* **Type Safety**: Prevents assigning wrong object types to parameters
* **UI Integration**: Picker dialogs filter to show only compatible objects
* **Auto-completion**: IDEs and editors can suggest valid objects
* **Documentation**: Makes code intent clear (what kind of object is expected)
* **Validation**: Runtime checks ensure correct object types
**Example: Type-Safe Design Check**
```xml
```
**Creating Custom Types:**
```xml
```
### 11. Required and Pick Flags
The `Required` and `Pick` flags on ParamInfo objects control parameter validation and UI behavior.
**Required Flag:**
```xml
```
* `Required="1"`: Parameter MUST have a valid value before object can be used
* UI prevents saving/executing until required parameters are filled
* Combines with ParamGuard: only required when guard condition is true
**Example:**
```xml
```
**Pick Flag:**
```xml
```
* `Pick="1"`: Adds a picker button in the UI next to the parameter
* Clicking picker opens object selection dialog
* Dialog is filtered by parameter's Type (if custom type specified)
**Example:**
```xml
```
**Combined Usage:**
```xml
```
**Conditional Required:**
```xml
```
**List with Required:**
```xml
```
**Best Practices:**
* Always use `Required="1"` for critical parameters (girders, load cases, materials)
* Combine `Required="1"` with `Pick="1"` for object references to guide users
* Use `Required` with `Min` on lists to enforce minimum item count
* Combine with ParamGuard to make parameters conditionally required
* Provide sensible default values when possible (reduces required fields)
**Example: Complete Parameter Configuration**
```xml
```
### 12. Advanced ParamInfo Attributes
Beyond the basic ParamInfo features, OpenBrIM provides advanced attributes for UI optimization, custom interactions, and reference management.
#### 12.1 ExpensiveComputation
Marks parameters as computationally expensive to enable UI performance optimizations.
**Purpose:** When set, the spreadsheet view caches computed values to avoid repeated evaluation of expensive expressions during rendering.
**Syntax:**
```xml
```
**Example:**
```xml
```
**When to use:**
* FEA result extractions (`force()`, `stress()`, `disp()`)
* Geometric calculations (`volume()`, `surfarea()`, `volumesurfareas()`)
* Nested `map()` operations over large datasets
* Complex iterative algorithms
* Any parameter that takes >100ms to compute
**Best Practices:**
* Combine with `ReadOnly="1"` for computed results
* Use for parameters accessed frequently in UI but rarely changed
* Don't overuse—only for genuinely expensive computations
#### 12.2 CustomCellActions
Provides custom context menu actions for spreadsheet cells, enabling specialized editing interfaces.
**Purpose:** Adds custom actions to the right-click context menu in the spreadsheet view for interactive parameter editing.
**Syntax:**
```xml
```
**Available Actions:**
**Stiffness/Matrix Editing:**
* `"6x6Stiffness"` - Edit 6x6 stiffness matrix (for nodes with StiffnessMatrix parameter)
* `"EditStiffness"` - Edit spring stiffness values
* `"EditStiffnessTx"`, `"EditStiffnessTy"`, `"EditStiffnessTz"` - Directional translational stiffness
* `"EditStiffnessRx"`, `"EditStiffnessRy"`, `"EditStiffnessRz"` - Directional rotational stiffness
**Analysis Curves:**
* `"EditMomentCurvature"` - Edit moment-curvature relationship
* `"ResponseSpectrumCurve"` - Edit response spectrum curves
* `"PrestressingDetails"` - Display tendon prestressing details
**CADD Drawing:**
* `"CADPolyDraw"` - Draw polygon in CADD view
* `"CADPolyLineDraw"` - Draw polyline in CADD view
* `"CADRectDraw"` - Draw rectangle in CADD view
* `"CADPointDraw"` - Draw point in CADD view
* `"CADCircleDraw"` - Draw circle in CADD view
* `"CADLineDraw"` - Draw line in CADD view
**Other:**
* `"DuplicateSection"` - Duplicate section from ExtObj
* `"EditPath"` - Edit path points interactively
* `"EditSpanLoc"` - Edit span locations
* `"CentFactor"`, `"WheelFactor"`, `"ImpactFactor"` - Edit load factors
**Example:**
```xml
```
**Best Practices:**
* Only add actions relevant to the parameter's purpose
* Combine with ParamGuard to show actions contextually
* Use CADD actions for geometric input parameters
* Use stiffness actions for FEA boundary condition parameters
#### 12.3 RefParam
Establishes bidirectional references between objects for automatic dependency tracking.
**Purpose:** When an object is added/removed, automatically updates reference lists in related objects.
**Syntax:**
```xml
```
**How it works:**
* When object is created, its name is added to the target list
* When object is deleted, its name is removed from the target list
* Maintains synchronized references across the project
**Example:**
```xml
```
**Use Cases:**
* Maintaining lists of available load cases
* Tracking which supports reference a pier
* Maintaining object inventories
* Automatic dropdown population
**Note:** RefParam creates two-way dependencies. Use carefully in modular library objects.
#### 12.4 ReadOnly (Enhanced)
Makes parameters read-only in the UI while allowing programmatic updates.
**Purpose:** Prevents manual editing of computed values while displaying them to users.
**Syntax:**
```xml
```
**Visual Effect:**
* Text color: Gray (#626262)
* Cell editing: Disabled
* Custom actions: Hidden
**Example:**
```xml
```
**Common Pattern - Readonly Computed Quantities:**
```xml
```
**Best Practices:**
* Always use for derived/computed values
* Combine with ExpensiveComputation for performance
* Use for displaying object properties (e.g., `Material.N`, `Section.Depth`)
* Don't use for input parameters
### 13. Coordinate Systems (CoorSys)
User-defined coordinate systems for local transformations and FEA boundary conditions.
**Purpose:** Define custom local coordinate systems using origin point and rotation (quaternion or Euler angles).
**Type:** `CoorSys`
**Key Parameters:**
* **X, Y, Z**: Origin coordinates
* **Qx, Qy, Qz, Qw**: Quaternion rotation components
* **Alpha, Beta, Gamma**: Alternative Euler angles (ZYX order)
**Quaternion Representation:**
* Qx, Qy, Qz: Vector part
* Qw: Scalar part
* Identity (no rotation): \[0, 0, 0, 1]
**Syntax:**
```xml
```
**Example - Using Quaternions:**
```xml
Qy="0"
Qz="0"
Qw="0.707"
X="0" Y="0" Z="0"/>
```
**Example - Using with Objects:**
```xml
```
**Quaternion Conversion Formulas:**
```
For rotation by angle θ about axis (nx, ny, nz):
Qx = nx * sin(θ/2)
Qy = ny * sin(θ/2)
Qz = nz * sin(θ/2)
Qw = cos(θ/2)
Common rotations:
Z-axis by θ: Qx=0, Qy=0, Qz=sin(θ/2), Qw=cos(θ/2)
Y-axis by θ: Qx=0, Qy=sin(θ/2), Qz=0, Qw=cos(θ/2)
X-axis by θ: Qx=sin(θ/2), Qy=0, Qz=0, Qw=cos(θ/2)
```
**Use Cases:**
* Skewed bridge piers
* Rotated foundations
* Local coordinate systems for boundary conditions
* Transformed geometry placement
* Consistent node positioning
**Best Practices:**
* Use quaternions for single-axis rotations (more intuitive)
* Quaternions avoid gimbal lock issues
* Set origin at logical reference point
* Document rotation axis and angle in description
* Verify coordinate system orientation in 3D view
### 16. Object Attributes for Library Development
#### 16.1 Override Attribute
Marks a group as overrideable by derived objects.
**Purpose:** Allows child objects to override entire groups of parameters when inheriting.
**Syntax:**
```xml
```
**Example:**
```xml
```
**Use Cases:**
* IFC export configurations
* Material overrides
* Display settings
* Analysis options
#### 16.2 Opacity Attribute
Controls 3D object transparency.
**Purpose:** Sets opacity for visualization (0.0 = transparent, 1.0 = opaque).
**Syntax:**
```xml
```
**Range:** 0.0 to 1.0
**Example:**
```xml
```
**Opacity Inheritance:**
* Child objects inherit parent opacity unless explicitly set
* `SpecifiedOpacity` and opacity overrides can modify behavior
* Final opacity = min(own opacity, parent opacity, overrides)
**Use Cases:**
* Highlighting active elements
* Showing/hiding secondary geometry
* Construction sequence visualization
* Context geometry display
**Best Practices:**
* Use 1.0 for primary structural elements
* Use 0.3-0.7 for reference geometry
* Use 0.0 to hide (better than Guard for temporary hiding)
* Consider performance impact of many transparent objects
### 13. Library Organization and Template System
OpenBrIM provides a comprehensive system for organizing library objects, workflows, and templates using metadata attributes. These attributes control how objects appear in the library tree view, template screens, and project workflows.
#### 13.1 Core Organization Attributes
**Metadata Attributes:**
* `Tags`: Comma-separated tags for filtering and categorization
* `ObjLabel`: User-friendly display name (appears in UI)
* `Category`: Hierarchical organization path (use `:` separator)
* `Role`: Object role ("WorkFlow", "Template", "Input", etc.)
* `DocumentURL`: Link to online documentation
* `ObjectVersion`: Version number for tracking updates
* `Deprecated`: If "1", marks object as deprecated
#### 13.2 Tags Attribute
Tags enable filtering, categorization, and special behaviors for library objects.
**Syntax:**
```xml
Tags="@tag1,tag2,tag3,..."
```
**Common Tag Categories:**
**Geographic/Standard Tags:**
* `@usastandard`: US design standards (AASHTO, ACI, AISC)
* `@eustandard`: European standards (Eurocode)
* `@aashto`, `@aci`, `@aisc`: Specific code standards
**Bridge Type Tags:**
* `@steelIGirder`: Steel I-girder bridges
* `@precastIGirder`: Precast concrete I-girders
* `@splicedIGirder`: Spliced girder systems
* `@concreteBox`: Concrete box girders
**Functional Tags:**
* `@workflow`: Workflow definition object
* `@workflowtemplate`: Template with workflow structure
* `@release`: Ready for production use
* `@secondlayer`: Secondary-level component
**Special Tags:**
* `@doc:URL`: Embeds documentation link
* `@img:ImageName`: Specifies template image
**Example:**
```xml
```
#### 13.3 Role Attribute
The `Role` attribute defines how OpenBrIM treats and displays the object.
**Role Values:**
| Role | Purpose | Behavior |
| ---------- | ------------------------ | ---------------------------------------------------- |
| `WorkFlow` | Workflow definition | Appears in workflow tree with hierarchical structure |
| `Template` | Project template | Appears on "Open Project" screen with thumbnail |
| `Input` | User input parameter | Highlighted in parameter list, shows in input forms |
| `Export` | Output/result parameter | Shown in results, available for export |
| `Private` | Internal parameter | Hidden from standard UI views |
| `Import` | Imported/referenced data | Marks data from external sources |
**Example: Workflow Object**
```xml
```
**Example: Template Object**
```xml
```
#### 13.4 Category Attribute
The `Category` attribute controls how objects and parameters are organized in the UI. **Important:** The behavior differs significantly between object-level and parameter-level usage.
**13.4.1 Object-Level Categories (T="Project" Objects)**
Objects with `T="Project"` support **hierarchical categories** using the `::` separator:
**Syntax:**
```xml
```
**Example:**
```xml
```
This creates a tree structure in the library browser:
```
Bridge Workflow/
└── CADD/
└── OBPCADDFoundationPlan
```
**Multiple Levels:**
```xml
Category="Level1::Level2::Level3"
```
**Common Category Hierarchies:**
**Project Templates:**
```
Project Templates::Concrete Bridge Workflows
Project Templates::Steel Bridge Workflows
Project Templates::All-in-One Bridge Workflows
```
**Generative:**
```
Generative::Modeling
Generative::FEA
Generative::Deliverables
```
**Databases:**
```
Databases::Time Dependent
Databases::Materials
Databases::Sections
```
**Use Cases:**
* Library organization
* Template categorization
* Code check object grouping
* Project structure hierarchy
***
**13.4.2 Parameter-Level Categories (P Elements)**
Parameters support **single-level categories only** - the `::` syntax is **NOT supported**.
**Syntax:**
```xml
```
**✅ CORRECT Examples:**
```xml
```
**❌ INCORRECT - Will Not Work:**
```xml
❌
❌
```
**How It Appears in UI:** Parameters are grouped by their Category value in the parameter panel:
```
┌─ Detailing ────────────┐
│ DispStaMarker [1] │
│ MarknthDist 1200 │
└────────────────────────┘
┌─ Column ───────────────┐
│ DispColumn [1] │
│ DispColumnFtgPile [0] │
└────────────────────────┘
```
**Use Cases:**
* Grouping input parameters in UI
* Organizing display settings
* Categorizing geometry parameters
* Database field organization
***
**13.4.3 Key Differences**
| Feature | Object Category | Parameter Category |
| ------------------ | -------------------------- | ------------------------ |
| **Syntax** | `Category="Parent::Child"` | `Category="SingleLevel"` |
| **Hierarchy** | ✅ Multi-level supported | ❌ Single level only |
| **`::` Separator** | ✅ Supported | ❌ **Not supported** |
| **UI Location** | Library browser tree | Parameter panel groups |
| **Applies To** | `` objects | `` parameters |
| **Example** | `"Bridge Workflow::CADD"` | `"Detailing"` |
***
**13.4.4 Common Mistakes**
**Mistake #1: Using `::` in Parameter Categories**
```xml
❌
❌
✅
✅
```
**Why:** OpenBrIM/ParamML does not parse `::` in parameter Category attributes. The entire string is treated as a single category name.
**Mistake #2: Confusing Nested Groups with Category Hierarchy**
Nested groups (``) provide organizational structure in XML but **do NOT create category hierarchy** for parameters:
```xml
```
Parameters inherit nothing from parent group names - they must specify their own Category.
***
**13.4.5 Best Practices**
**For Objects:**
* Use descriptive hierarchies: `"Domain::Subdomain::Type"`
* Keep depth reasonable (2-4 levels maximum)
* Match existing library structure conventions
* Use `::` (double colon) as the separator
**For Parameters:**
* Use concise, clear category names
* Group related parameters together
* Common categories: "General", "Geometry", "Properties", "Display", "Advanced", "Detailing"
* Coordinate with existing parameter categories in your library
* Do NOT use `::` separator
**Mixed Usage Example:**
```xml
```
***
**13.4.6 Why the Difference?**
**Technical Reason:**
* Object categories organize the **library structure** (file/folder metaphor)
* Parameter categories organize **UI panels** (flat grouping)
* Different UI contexts require different organizational models
**Design Reason:**
* Parameter panels work best with **flat, scannable groups**
* Deep hierarchies in parameter panels would be cumbersome
* Library browsers benefit from **tree navigation**
***
#### 13.5 WorkFlow and WorkFlowItem Objects
Workflows provide structured, step-by-step guidance for bridge modeling.
**WorkFlow Structure:**
```xml
```
**WorkFlowItem Attributes:**
* `ObjectType`: Reference to the library object type (use `@` prefix)
* `Label`: Display name in workflow tree
* `ObjectVersion`: Minimum required version
* `DocumentURL`: Link to documentation
* `IconStageCons`: If "1", shows construction stage icon
**Complete Workflow Example:**
```xml
```
#### 13.6 Template Objects
Templates appear on the "Open Project" screen and provide pre-configured starting points.
**Template Structure:**
```xml
```
**Special Tags for Templates:**
* `doc:URL`: Documentation link (e.g., `doc:https://docs.openbrim.com/...`)
* `img:ImageName`: Image identifier for thumbnail (e.g., `img:AllInOneBridgeImg`)
**Example: All-in-One Template**
```xml
```
#### 13.7 Version Management
Track object versions for compatibility and updates.
**ObjectVersion Attribute:**
```xml
```
**Versioned Object References:**
```xml
```
**Deprecation:**
```xml
```
#### 13.8 Documentation Integration
Link objects to external documentation for user guidance.
**DocumentURL Attribute:**
```xml
```
**Documentation in Tags:**
```xml
Tags="@usastandard,release,doc:https://docs.openbrim.org/quick-guides/all-in-one-bridge-combination-of-workflows"
```
#### 13.9 Organization Best Practices
**1. Use Consistent Naming:**
```xml
```
**2. Hierarchical Categories:**
```xml
Category="Loading:Static Loads:Surface Loads"
Category="Code Check Objects:Superstructure Checks:Girder Checks"
```
**3. Appropriate Tags:**
```xml
Tags="@usastandard,steelIGirder,codecheck,release"
Tags="@generic,stuff,things,misc,other"
```
**4. Documentation Links:**
```xml
```
**5. Version Tracking:**
```xml
```
**6. Template Organization:**
```xml
```
#### 13.10 Complete Organization Example
```xml
```
#### 13.11 Template Display System
Templates with `Role="Template"` appear on the "Open Project" screen.
**Display Elements:**
* **Thumbnail**: Specified by `img:ImageName` tag
* **Title**: From `ObjLabel` attribute
* **Description**: Generated from category and tags
* **Documentation**: From `doc:URL` tag
**Example Template Card Display:**
```
┌─────────────────────────────┐
│ [Thumbnail Image] │
│ │
│ All-in-One Bridge Workflow │ ← ObjLabel
│ │
│ Supports steel, precast, │ ← Generated from
│ and spliced girder bridges │ tags/content
│ │
│ [Documentation Link] │ ← doc: tag
└─────────────────────────────┘
```
**Key Features:**
* Searchable by tags and labels
* Filterable by category
* Clickable documentation links
* Visual preview via thumbnail
#### 13.12 Database Objects
Database objects are special library containers that organize collections of reusable components like sections, materials, or reinforcement patterns. They appear in the library tree under the "Databases" category and provide pre-configured objects that users can select and use in their projects.
**Database Object Characteristics:**
* `Category="Databases:..."`: Places object in Databases category
* `Tags` includes `@database`: Marks as database object
* Contains grouped collections of related objects
* Each item has `Role="Input"` parameters for configuration
**Database Structure:**
```xml
```
**Common Database Categories:**
| Category | Purpose | Typical Contents |
| ----------------------------- | ---------------------- | --------------------------------- |
| `Databases:Section Database` | Cross-section shapes | Girders, barriers, columns, piles |
| `Databases:Material Database` | Material properties | Concrete grades, steel types |
| `Databases:Rebar Database` | Reinforcement patterns | Bar sizes, spacing patterns |
| `Databases:Vehicle Database` | Load vehicles | AASHTO trucks, railroad loads |
| `Databases:Load Database` | Load definitions | Wind, seismic, temperature |
**Example: Barrier Section Database**
```xml
```
**Database Organization Patterns:**
**1. By Agency/Standard:**
```xml
```
**2. By Type/Category:**
```xml
```
**3. By Size Range:**
```xml
```
**Parametric Database Objects:**
Database objects can be parametric, allowing users to configure dimensions:
```xml
```
**Fixed Database Objects:**
For standard, non-parametric objects (like agency-specific standards):
```xml
```
**Database Object Usage:**
Users access database objects in two ways:
**1. Direct Reference:**
```xml
```
**2. Object Picker UI:**
```xml
```
**Best Practices for Database Objects:**
**1. Organization:**
```xml
```
**2. Naming Conventions:**
```xml
```
**3. Documentation:**
```xml
```
**4. Units:**
```xml
```
**5. Tags:**
```xml
Tags="@database,usastandard,steelIGirder,precastIGirder,concreteBoxGirder,release"
```
**Database Object Categories:**
**Section Databases:**
```xml
Category="Databases:Section Database"
```
**Material Databases:**
```xml
Category="Databases:Material Database"
```
**Reinforcement Databases:**
```xml
Category="Databases:Rebar Database"
```
**Load Databases:**
```xml
Category="Databases:Vehicle Database"
Category="Databases:Load Database"
```
**Example: Material Database**
```xml
```
**Database Integration with Projects:**
Projects reference database objects for consistent, standardized components:
```xml
```
**Summary:**
Database objects provide:
* **Centralized libraries** of standard components
* **Reusable templates** for common elements
* **Agency standards** compliance
* **Parametric flexibility** for customization
* **Consistent organization** across projects
* **Easy selection** via UI pickers
Key attributes:
* `Category="Databases:Type"`
* `Tags` includes `@database`
* Organized in hierarchical groups
* Parameters marked with `Role="Input"` for user configuration
* Complete units and metadata definitions
## Summary
The OpenBrIM parametric engine provides a powerful XML-based system for creating reusable, parametric bridge components. Key principles:
* **Objects** form hierarchical structures with names and types
* **Parameters** store values and expressions that define object behavior
* **Expressions** create parametric relationships between objects and parameters
* **Repeat** objects enable arrays and iterations for creating multiple instances (use ONLY for objects, NOT for parameter loops)
* **map(), filter(), reduce()** for all parameter transformations (10-100x faster than Repeat)
* **ParamInfo** provides rich metadata for parameter UI, validation, and behavior
* Advanced features: ExpensiveComputation, CustomCellActions, RefParam, ReadOnly
* **Guards** control conditional object inclusion (Guard) and parameter visibility (ParamGuard)
* **Metadata attributes** (Tags, ObjLabel, Category) organize library components
* **Extends** enables template-based inheritance with versioning
* **Custom types** provide type-safe object references
* **Section objects** define cross-sectional geometry for structural analysis
* **FEA nodes** support MergeNearest, MergeSameLoc, StiffnessMatrix for advanced mesh control
* **FEA elements** support IsRigid, BetaAngle, CastingDay, and node releases for connection modeling
* **CoorSys** defines user coordinate systems with quaternions for local transformations
* **Override** and **Opacity** attributes for library flexibility and visualization
* **Performance features** like StaticParams and ExpensiveComputation optimize large-scale parametric models
* **Concise XML** should be preferred when metadata isn't required
* **Inheritance** is achieved by using an object's name as the Type of a new object, allowing you to create variations by overriding specific parameters
By following this guide, AI agents can create sophisticated parametric bridge models that are flexible, reusable, and maintainable.