Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

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 <O T="Export"> 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., <O N="MyExport" T="Export">). This is useful when extending objects, as named Export groups can be overridden with Override="1".

For more details: See AI-Export.md

4. Library Objects (Templates)

5. Extending Objects

Use Extends attribute to inherit from other objects. For multiple inheritance, use array syntax.

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

8. Repeat Loops

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

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: <O T="Point" .../>

  • Comments for clarity: <!-- Description -->

Step 4: Parameter Best Practices

  • Use Role="Input" for user-editable values (automatically exported)

  • Place computed results inside <O T="Export"> 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

FEA Mesh Generation

Alignment-Based Positioning

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

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)

Ordering the Parameter Tabs

An object's parameter sheet has one tab per Category, in the order each category's first parameter appears. To choose the order, declare CategoryOrder as a list of category names, written as strings:

  • Named categories come first, in the listed order; the rest follow in their usual order.

  • Names must match the parameters' Category values exactly. A name the object has no parameters for is skipped, so one list can serve a whole family.

  • Put it directly on the object's root <O>. Inside a Group it is not found.

  • It is an ordinary parameter, so Extends inherits it: declare it once on the family's base object, and redeclare it on a descendant to override it. With several bases, the first one listed in Extends that declares it wins, so declare it on the family base rather than on a shared mixin.

  • It is evaluated on the library definition, so it cannot depend on a placed object's inputs.

  • IFC, Quantities and Referencing Objects stay last unless the list names them.

  • Write each name in quotes. [Capacity,Gap] would be read as references, and the whole list is then ignored (the browser console says why).

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 <O T="Export"> 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

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

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

4. Performance: Repeat vs map() and StaticParams

Check: Using Repeat only for objects, map() for data transformations

Check: Using StaticParams for constant parameters in Repeat loops

IMPORTANT: StaticParams value must be enclosed in square brackets [].

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:

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.

How: write an OBPBackwardsCompatibility_<yymmdd> migration object and register it in the catalog. The full recipe, the operation types, the expression pitfalls (length(NULL) throws, .EQ. NULL coerces, the map lambda shadows x) and the test path are in AI-Backwards-Compatibility-Guide.md. The same applies to reordering or adding ParamInterface columns and to removing an object type.

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:

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:

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

    • 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

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 <O N="..." T="DesignRun"> group in the DR file

  • Verify EVERY Base Role="Input" parameter has a corresponding <P N="paramName" .../> 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):

Common Issues:

  1. Forgotten Input Parameters: New Role="Input" added to Base but not mapped in DR

  2. Spacing Errors: N="param " (with space) vs N="param" (correct)

  3. Typos: Parameter name misspellings

  4. Version Mismatch: DR references old Base version, missing new parameters

  5. Unintended Non-Input Overrides: DR overrides calculated parameters (MUST FIX)

Best Practice:

  • Always map ALL Role="Input" parameters from Base to DR (mandatory)

  • NEVER override non-Input parameters in DesignRun

  • When adding new Role="Input" to Base → immediately add to corresponding DR

  • Use automated scripts during code review to verify completeness

  • If non-Input override is found → add Role="Input" to Base or remove override from DR


Review Process:

When user says "review the code":

  1. ✅ Validate parameter names against __dep__ files

  2. ✅ Check complete overrides for all referenced child objects

  3. ✅ Verify coordinate format (inline X-Y-Z, no spaces)

  4. ✅ Check Repeat optimization (use map() for data, StaticParams for constants)

  5. ✅ Check formatting (no spaces in math: i*12 not i * 12)

  6. ✅ Check input parameter renames (if workflow files exist and parameters renamed, warn user about backwards compatibility)

  7. ✅ Check DesignRun completeness (for DR objects with T="DesignRun": find the Base object via LibObjTypeName parameter, verify all Base Role="Input" parameters are mapped in DesignRun group, flag any non-Input parameter overrides)

Important Notes

⚠️ Always read the AI documentation guides before starting work (start with AI-Parametric-Engine-Guide.md)

⚠️ Understand file types:

  • Main objects (ObjectName.xml) - Your working files

  • Dependencies (__dep__ObjectName.xml) - Referenced library objects

  • Guides (.md files) - Documentation to help you understand the system

⚠️ FEA-specific content belongs in AI-FEA-Guide.md, not AI-Parametric-Engine-Guide.md

⚠️ Use inline X-Y-Z attributes for all coordinate definitions

⚠️ No spaces in mathematical expressions (e.g., i*12 not i * 12)

⚠️ Use map() for data transformations, Repeat only for objects

⚠️ Type name is Surface not Surface3D in XML (Surface3D is TypeScript class name)

⚠️ Parameter Scope and Shared Parameters:

  • Parameters in sibling Groups under the same parent CAN access each other

  • When parameters are used by multiple sibling Groups, consider organizing them:

    • Option 1: Keep shared parameters in one Group if primary usage is there (sibling access works)

    • Option 2: Move to parent level for clearer organization and better documentation

    • Both approaches work technically, but Option 2 is preferred for maintainability

Example: Shared parameters between CADD drawings and Section geometry:

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

Last updated