> For the complete documentation index, see [llms.txt](https://docs.openbrim.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openbrim.org/developers/llm-guides/ai-paramml-readme.md).
# ParamML README
## Overview
You are working with **OpenBrIM's Parametric Engine (ParamML)**, a powerful XML-based parametric modeling system for bridge engineering and infrastructure projects. This system enables the creation of intelligent, data-driven bridge components through parametric expressions, inheritance, and lazy evaluation.
## What is ParamML?
ParamML (Parametric Markup Language) is an XML-based language that defines:
* **Parametric Objects**: Hierarchical objects with parameters and expressions
* **Library Components**: Reusable templates for bridge elements (girders, columns, decks, etc.)
* **3D Geometry**: Points, Lines, Surfaces, and Volumes
* **FEA Models**: Finite Element Analysis meshes and boundary conditions
* **Code Checks**: Design verification and compliance calculations
* **Reports**: Automated documentation and analysis results
## File Structure
When you download a branch, you'll receive:
### 1. Branch XML Files (Main Objects)
* `ObjectName.xml` - The library objects you're working on
* These are the objects that were modified or developed in this branch
### 2. Dependency XML Files (Referenced Objects)
* `__dep__ObjectName.xml` - Library objects that are referenced by your main objects
* Prefixed with `__dep__` to distinguish them from your working files
* These are automatically downloaded based on the `subobjtypes` (object type references) in your main objects
* **Example**: If your girder object uses a `StandardSection` object, `__dep__StandardSection.xml` will be downloaded
### 3. AI Documentation Files (.md)
These are guides to help you understand and work with the ParamML system:
**Core Guides (Read These First):**
* `AI-Parametric-Engine-Guide.md` - **ESSENTIAL - Read FIRST**
* Explains Objects, Parameters, Expressions, Lazy Evaluation
* Covers Repeat loops, Guards, Library Objects, Export objects
* Distance-based parameter resolution
* Performance optimization patterns
* `AI-ParamML-Functions-Reference.md` - **Function library reference**
* Mathematical, geometric, and alignment functions
* Array operations (map, filter, reduce)
* String manipulation and utility functions
**Task-Specific Guides (Read When Needed):**
* `AI-FEA-Guide.md` - Finite Element Analysis
* FENode, FELine, FESurf element types
* Boundary conditions, loads, analysis cases
* Mesh generation and node merging
* `AI-3D-Visualization-Guide.md` - 3D Geometry
* Point, Line, Surface, Volume primitives
* Texture mapping and materials
* Parametric shapes and extrusions
* `AI-Bridge-Alignment-Guide.md` - Bridge Alignments
* Horizontal and vertical alignment functions
* Superelevation and cross-slope
* Station-based positioning
## Key Concepts (Quick Reference)
### 1. XML Object Structure
```xml
```
### 2. Parameter Roles
* `Role="Input"` - User-editable, automatically exported (accessible to other objects)
* `Role="Private"` - Internal calculations, not exported
* No role - Private by default
### 3. Export Objects
To export computed parameters, place them inside `` containers. Parameters inside Export objects are automatically accessible to other objects.
**Important Dependency Rule:** If an exported parameter depends on other parameters, those dependencies must also be exported OR have `Role="Input"`.
**Naming Export Objects:** Export objects can have names (e.g., ``). This is useful when extending objects, as named Export groups can be overridden with `Override="1"`.
```xml
```
**For more details:** See `AI-Export.md`
### 4. Library Objects (Templates)
```xml
```
### 5. Extending Objects
Use `Extends` attribute to inherit from other objects. For multiple inheritance, use array syntax.
```xml
```
### 6. Object References
* `@ObjectName|ObjectType` - Reference by name and type
* `ObjectName.ParameterName` - Access object parameters
* `RepeatName[i].ParameterName` - Array access in Repeat loops
* `RepeatName[i-1].ParameterName` - Access previous iteration
### 7. Coordinate Format
**ALWAYS use inline X-Y-Z attributes (no spaces in expressions):**
```xml
```
### 8. Repeat Loops
```xml
```
### 9. Performance Rules
* **Use Repeat ONLY for creating objects** (Points, Lines, FENodes, etc.)
* **Use map() for data transformations** - 100x faster than Repeat
* **Use filter() for selecting subsets**
* **Use reduce() for aggregations**
```xml
```
## Working with This Code
### Step 1: Read Documentation Guides
**Before starting any task**, read the relevant AI guides:
1. **Always read first**: `AI-Parametric-Engine-Guide.md` (core foundation)
2. If working with FEA: `AI-FEA-Guide.md`
3. If using functions: `AI-ParamML-Functions-Reference.md`
4. If working with 3D geometry: `AI-3D-Visualization-Guide.md`
5. If working with alignments: `AI-Bridge-Alignment-Guide.md`
### Step 2: Understand the Object Type
* **Library Objects**: `T="Project"` with Tags - reusable templates
* **Geometry**: Point, Line, Surface, Volume
* **FEA**: FENode, FELine, FESurf, FEGroup
* **Structural**: Girder, Column, Deck, Bearing
* **Analysis**: AnalysisCase, LoadCase, LoadCombination
### Step 3: Follow XML Formatting Standards
* Use inline X-Y-Z attributes for coordinates
* No spaces around operators in expressions (e.g., `i*12` not `i * 12`)
* Self-closing tags when no children: ``
* Comments for clarity: ``
### Step 4: Parameter Best Practices
* Use `Role="Input"` for user-editable values (automatically exported)
* Place computed results inside `` containers
* Include `UT` (UnitType) for engineering values
* Add `D` (Description) for documentation
* Ensure exported parameters only depend on other exported params or `Role="Input"` params
### Step 5: Test Expressions
* All expressions use JavaScript syntax
* Lazy evaluation - computed only when needed
* Ternary operators: `condition ? trueValue : falseValue`
* Math functions: `sin()`, `cos()`, `sqrt()`, `abs()`, etc.
* Array functions: `map()`, `filter()`, `reduce()`, `sum()`, `max()`, `min()`
## Common Patterns
### Creating Library Components
```xml
```
### FEA Mesh Generation
```xml
```
### Alignment-Based Positioning
```xml
```
### Referencing Objects Pattern (Bidirectional References)
Use this pattern to create automatic two-way references between parent and child objects.
**Use Cases:**
* Girder → Cross Frames (bracings)
* Pier Column → Foundation
* Deck → Barrier
```xml
```
**Key Points:**
* Parent has `ReadOnly="1"` list in "Referencing Objects" group
* Child uses `RefParam="@bracings"` to register itself with parent
* System automatically adds/removes child from parent's list
* Other objects can navigate through references (e.g., Deck takes girder list, then accesses `girder.bracings` to reach cross frame data)
## File Types
* `.md` - Markdown documentation (AI guides)
* `.xml` - XML data files (library objects, type definitions)
* `.ts` - TypeScript source code (ParamML engine implementation)
## Common Tasks
### Adding New Library Objects
1. Read: `AI-Parametric-Engine-Guide.md` (Library Objects section)
2. Define `T="Project"` with proper Tags and Category
3. Add `Role="Input"` parameters for user configuration (automatically exported)
4. Add internal calculations (no role - private by default)
5. Create `` for computed results that need to be accessible externally
6. Ensure exported params only depend on other exported params or `Role="Input"` params
### Creating FEA Models
1. Read: `AI-FEA-Guide.md`
2. Create nodes with `T="FENode"` (use X, Y, Z attributes)
3. Create elements (FELine, FESurf, FEVolume)
4. Define boundary conditions (Tx, Ty, Tz, Rx, Ry, Rz)
5. Create analysis cases and load combinations
6. Reference nodes using `@NodeName|FENode`
### Working with 3D Geometry
1. Read: `AI-3D-Visualization-Guide.md`
2. Use Point, Line, Surface, Volume types
3. Define coordinates with inline X, Y, Z attributes
4. Use Repeat for parametric arrays
5. Apply materials and textures as needed
## Code Review Checklist
When reviewing ParamML code, systematically check for these common issues:
### 1. Parameter Name Validation
**Check:** All parameter overrides use correct names from parent object
```xml
```
**How to Check:**
1. Open `__dep__ParentObjectName.xml` file
2. List all `Role="Input"` parameters
3. Verify each override matches an actual parameter name
4. Flag typos or non-existent parameter names
### 2. Complete Parameter Overrides (Extends)
**Check:** All parameters affecting referenced child objects are overridden
```xml
```
**How to Check:**
1. Find all references to child objects: `ObjectName.ChildGroup.Property`
2. Open `__dep__` file, trace which input parameters affect those child objects
3. Verify ALL those parameters are either:
* Overridden with appropriate values
* Left as default AND defaults make sense for this use case
### 3. Coordinate Format Standards
**Check:** All coordinates use inline X-Y-Z attributes, no spaces in math
```xml
```
### 4. Performance: Repeat vs map() and StaticParams
**Check:** Using Repeat only for objects, map() for data transformations
```xml
```
**Check:** Using StaticParams for constant parameters in Repeat loops
**IMPORTANT:** StaticParams value must be enclosed in square brackets `[]`.
```xml
...
```
**How to Check:**
1. Find all Repeat loops
2. Identify parameters that don't depend on loop variable (i, j, etc.)
3. Add those parameter names to StaticParams attribute
4. Format: `StaticParams="[Param1,Param2,Param3]"` (with square brackets!)
### 5. FEA Content Separation
**Check:** FEA-specific code should reference AI-FEA-Guide.md
* FENode, FELine, FESurf, FEGroup → FEA-specific
* Point, Line, Surface, Volume → General geometry
### 6. Input Parameter Renaming - Breaking Changes
**Check:** Renaming `Role="Input"` parameters in **workflow objects** requires backwards compatibility
**Critical Rule:** If a library object appears in a **Workflow** (check `*Workflow*.xml` files), renaming its `Role="Input"` parameters is a **breaking change** for end users.
**Why This Matters:**
* End users have saved projects with parameter values using old names
* Renaming parameters loses user's saved values (silent failure)
* Users must manually re-enter all values - **unacceptable UX**
**Problem Example:**
```xml
```
**Solution:**
If renaming `Role="Input"` parameters in workflow objects, **implement backwards compatibility** to preserve old parameter values. This ensures users don't lose their saved data when updating software versions.
**Best Practice:**
* **Check workflow files** before renaming to see if object is user-facing
* If object is in workflow → Backwards compatibility may be needed to preserve user data
* If object is NOT in workflow → Update dependent objects in same branch
* Document parameter renames in release notes
### 7. DesignRun Object Completeness Check (DR Objects)
**Check:** For DesignRun (DR) objects, verify all Base object's `Role="Input"` parameters are mapped in `T="DesignRun"` group
**What are DR Objects?**
* DR (DesignRun) objects are wrapper objects that execute Base library objects with user-provided inputs
* They map user inputs from the DR object's interface to the Base object's parameters
* Pattern: `*OBPDR_*.xml` files contain DR objects, they reference `*OBPBase_*.xml` files
* File naming: Base object `OBPBase_MyObject.xml` → DR object `OBPDR_MyObject.xml`
**Structure:**
```xml
```
**Why This Matters:**
* **Missing Input parameters** → Base uses default values instead of user inputs → **Silent failures**
* **Users lose control** over critical design parameters
* **Results may be incorrect** without any warning
* Incomplete mapping is the **#1 cause** of DR object bugs
**⚠️ WARNING: DesignRun Non-Input Parameter Override**
DesignRun has a **dangerous capability** that must be carefully controlled:
**The Problem:**
* DesignRun can override **ANY parameter** in the Base object, not just `Role="Input"` parameters
* When you override a non-Input parameter, **ALL occurrences** of that parameter in the Base object scope are overridden
* This is **NOT recommended** and should be avoided in most cases
**Example - Unintended Override:**
```xml
```
**When This Happens:**
* ❌ **Breaks Base object's internal logic** - calculated parameters no longer use intended values
* ❌ **Creates maintenance nightmare** - changes to Base 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
**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 Base object**
```xml
```
* Makes it officially part of the Base object's API
* Clear to all developers that this parameter is meant to be configurable
* Proper design pattern
2. **If parameter should remain internal:**
* Do NOT override it from DR
* Modify Base object logic if behavior needs to change
* Keep data override (DR) separate from logic (Base)
**How to Check:**
**Step 1:** Identify the Base object reference
```xml
```
**Step 2:** Extract all `Role="Input"` parameters from Base object
* Open the corresponding Base file (e.g., `OBPBase_MyObject.xml`)
* Find ALL parameters with `Role="Input"` attribute
* Create a list of these parameter names (these MUST be mapped)
**Step 3:** Verify each Base input exists in DesignRun group
* Check the `` group in the DR file
* Verify EVERY Base `Role="Input"` parameter has a corresponding `` entry
* Parameter names must match EXACTLY (no spaces, correct spelling)
**Step 4:** Check for non-Input parameter overrides
* Identify any parameters in DesignRun that are NOT `Role="Input"` in Base
* These are **problematic overrides** that should be flagged
* Review why these exist and if Base object should be modified instead
**Step 5:** Check for naming errors
* Watch for trailing/leading spaces: `N="param "` vs `N="param"`
* Watch for typos or case sensitivity issues
* Parameter names must match Base object exactly (character-by-character)
**Automated Check (PowerShell):**
```powershell
# Extract Base Role="Input" parameters
$baseLines = Get-Content 'OBPBase_MyObject.xml'
$baseInputs = @()
foreach ($line in $baseLines) {
if ($line -match 'Role="Input"' -and $line -match ']*T="DesignRun"') {
$designRunStart = $i
}
if ($designRunStart -gt -1 -and $designRunEnd -eq -1 -and $drLines[$i] -match '^\s*\s*$') {
$designRunEnd = $i
break
}
}
# Extract DesignRun parameters
$drParams = @()
for ($i = $designRunStart; $i -le $designRunEnd; $i++) {
if ($drLines[$i] -match '
```
## Getting Help
When you need clarification:
1. Check the relevant AI guide first (AI-Parametric-Engine-Guide.md, AI-FEA-Guide.md, etc.)
2. Search for similar examples in the guides
3. Check `__dep__` files to understand referenced object structures
## Summary
This is a sophisticated parametric modeling system for bridge engineering. The XML files define intelligent, data-driven components that:
* Automatically calculate results from input parameters
* Generate 3D geometry and FEA meshes
* Perform design checks and code compliance
* Update dynamically when parameters change
* Export computed results for use by other objects
* Reference other library objects (downloaded as `__dep__` files)
**Quick Start:**
1. Read `AI-Parametric-Engine-Guide.md` first
2. Examine your main XML files (`ObjectName.xml`)
3. Check `__dep__` files to understand dependencies
4. Follow formatting standards and best practices
5. Create robust, reusable parametric components
***
**Generated for AI Agents working with OpenBrIM ParamML Code**
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.openbrim.org/developers/llm-guides/ai-paramml-readme.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.