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

<O N="ObjectName" T="ObjectType">
  <P N="ParameterName" V="Expression" Role="Input" UT="Length"/>
  <!-- Child objects -->
</O>

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".

<!-- ❌ WRONG - param3 depends on non-exported parameters -->
<O T="Group">
  <P N="param1" V="12"/>
  <P N="param2" V="13"/>
</O>
<O T="Export">
  <P N="param3" V="param1+param2"/>  <!-- ERROR: param1, param2 not accessible -->
</O>

<!-- ✅ CORRECT - Option 1: Put dependencies in Export (with name for override) -->
<O N="Calculations" T="Export">
  <P N="param1" V="12"/>
  <P N="param2" V="13"/>
  <P N="param3" V="param1+param2"/>
</O>

<!-- ✅ CORRECT - Option 2: Use Role="Input" for dependencies -->
<O T="Group">
  <P N="param1" V="12" Role="Input"/>
  <P N="param2" V="13" Role="Input"/>
</O>
<O T="Export">
  <P N="param3" V="param1+param2"/>
</O>

<!-- Override Export in extended object -->
<O N="DerivedObject" T="Project" Extends="BaseObject">
  <O N="Calculations" T="Export" Override="1">
    <P N="param1" V="100"/>  <!-- Override values -->
    <P N="param3" V="param1*param2"/>  <!-- Override formula -->
  </O>
</O>

For more details: See AI-Export.md

4. Library Objects (Templates)

<O N="MyLibraryObject" T="Project" Tags="@library" ObjLabel="Display Name">
  <!-- Input parameters - automatically exported -->
  <P N="Width" V="24" Role="Input"/>
  <P N="Height" V="12" Role="Input"/>

  <!-- Export computed results -->
  <O N="Results" T="Export">
    <P N="Area" V="Width*Height"/>  <!-- Can access Input parameters -->
  </O>
</O>

<!-- Use the template -->
<O N="Instance1" T="MyLibraryObject">
  <P N="Width" V="30"/>  <!-- Override -->
</O>

5. Extending Objects

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

<!-- Single inheritance -->
<O N="DerivedObject" T="Project" Extends="BaseObject">
  <P N="Width" V="50"/>  <!-- Override parent parameter -->
</O>

<!-- Multiple inheritance -->
<O N="CombinedObject" T="Project" Extends="[BaseObject1,BaseObject2]">
  <!-- Inherits from both objects -->
</O>

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

<!-- ✅ CORRECT -->
<O T="Point" N="Pt" X="i*10" Y="0" Z="0" />
<O T="FENode" N="NODE" X="j*120" Y="i*120" Z="0">
  <P N="Tz" V="1"/>
</O>

<!-- ❌ WRONG (nested P elements, spaces in math) -->
<O T="Point" N="Pt">
  <P N="X" V="i * 10"/>
  <P N="Y" V="0"/>
  <P N="Z" V="0"/>
</O>

8. Repeat Loops

<O T="Repeat" N="Points" S="0" E="10" I="1" CTRL="i" i="0">
  <O T="Point" N="Pt" X="i*12" Y="0" Z="0" />
</O>

<!-- Access previous element -->
<O T="Repeat" N="Segments" S="0" E="5" I="1" CTRL="i" i="0">
  <O T="Segment" N="Seg">
    <P N="StartX" V="i > 0 ? Segments[i-1].EndX : 0"/>
  </O>
</O>

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

<!-- ✅ CORRECT -->
<P N="Results" V="map(InputList, x => x * 2)"/>

<!-- ❌ WRONG (creates unnecessary objects) -->
<O T="Repeat" N="Loop" S="0" E="99">
  <P N="Result" V="InputList[i] * 2"/>
</O>

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

<O N="StandardGirder" T="Project"
   Tags="@library,structural,girder"
   ObjLabel="Standard Steel Girder"
   Category="Structural Components:Girders">

  <!-- Inputs - automatically exported -->
  <P N="Span" V="120" Role="Input" UT="Length"/>
  <P N="Depth" V="72" Role="Input" UT="Length"/>

  <!-- Internal calculations (private, not exported) -->
  <P N="SectionModulus" V="Depth^3/6"/>

  <!-- Export results - can access Role="Input" parameters -->
  <O T="Export">
    <P N="Weight" V="Span*Depth*0.49" UT="Force"/>

    <!-- Export geometry -->
    <O T="Line" N="Geometry">
      <O T="Point" X="0" Y="0" Z="0"/>
      <O T="Point" X="Span" Y="0" Z="0"/>
    </O>
  </O>
</O>

FEA Mesh Generation

<!-- Node grid -->
<O T="Repeat" N="NodeRows" S="0" E="3" I="1" CTRL="i" i="0">
  <O T="Repeat" N="NodeCols" S="0" E="3" I="1" CTRL="j" j="0">
    <O T="FENode" N="NODE" X="j*120" Y="i*120" Z="0">
      <P N="Tz" V="(i==0 || i==3) ? 1 : 0"/>  <!-- Pin edges -->
    </O>
  </O>
</O>

<!-- Elements -->
<O T="Repeat" N="ElemRows" S="0" E="2" I="1" CTRL="i" i="0">
  <O T="Repeat" N="ElemCols" S="0" E="2" I="1" CTRL="j" j="0">
    <O T="FESurfMITC4" N="SHELL">
      <P N="Node1" V="@NODE_{i}_{j}|FENode"/>
      <P N="Node2" V="@NODE_{i}_{j+1}|FENode"/>
      <P N="Node3" V="@NODE_{i+1}_{j+1}|FENode"/>
      <P N="Node4" V="@NODE_{i+1}_{j}|FENode"/>
    </O>
  </O>
</O>

Alignment-Based Positioning

<O T="Point" N="BridgePoint"
   X="alignHX(Centerline, Station, Offset)"
   Y="alignHY(Centerline, Station, Offset)"
   Z="alignV(Centerline, Station)+alignT(Centerline, Station, Offset)">
  <P N="Station" V="100" Role="Input"/>
  <P N="Offset" V="10" Role="Input"/>
</O>

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

<!-- PARENT: Girder -->
<O N="OBPBase_Girder" T="Project">
    <O N="Referencing Objects" T="Group">
        <P N="bracings" V="[]" D="Cross Frames" Role="Input" Category="Referencing Objects" />
        <O T="ParamInfo" Param="bracings" Required="0" ReadOnly="1" />
    </O>
</O>

<!-- CHILD: CrossFrame -->
<O N="OBPBase_CrossFrame" T="Project">
    <O N="General" T="Group">
        <P N="Girders" V="[]" T="OBPBase_Girder" D="Girders" Role="Input" />
        <O T="ParamInfo" Param="Girders" Min="2" Max="2" Required="1" RefParam="@bracings"/>
    </O>
</O>

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

<!-- ❌ BAD: Typo in parameter name -->
<O N="MyGirder" Extends="StandardGirder">
  <P N="Lenght" V="120"/>  <!-- Typo: should be "Length" -->
</O>

<!-- ✅ GOOD: Correct parameter names -->
<O N="MyGirder" Extends="StandardGirder">
  <P N="Length" V="120"/>
</O>

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

<!-- ❌ BAD: Using StiffenerGroup but not setting NumStiffeners -->
<O N="MyGirder" Extends="StandardGirder">
  <P N="Length" V="120"/>
  <!-- Missing: NumStiffeners -->
</O>
<P N="Count" V="MyGirder.StiffenerGroup.Count"/>  <!-- BUG! -->

<!-- ✅ GOOD: Set all parameters affecting groups you use -->
<O N="MyGirder" Extends="StandardGirder">
  <P N="Length" V="120"/>
  <P N="NumStiffeners" V="5"/>
</O>
<P N="Count" V="MyGirder.StiffenerGroup.Count"/>

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

<!-- ❌ BAD -->
<O T="Point" N="Pt">
  <P N="X" V="i * 10"/>
</O>

<!-- ✅ GOOD -->
<O T="Point" N="Pt" X="i*10" Y="0" Z="0" />

4. Performance: Repeat vs map() and StaticParams

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

<!-- ❌ BAD: Using Repeat for calculations -->
<O T="Repeat" N="Loop" S="0" E="99">
  <P N="Result" V="InputList[i] * 2"/>
</O>

<!-- ✅ GOOD: Using map() -->
<P N="Results" V="map(InputList, x => x * 2)"/>

Check: Using StaticParams for constant parameters in Repeat loops

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

<!-- ❌ INEFFICIENT: Re-evaluates Spacing every iteration -->
<O T="Repeat" N="Points" S="0" E="10" CTRL="i">
  <P N="Spacing" V="12"/>
  <O T="Point" X="i*Spacing" Y="0" Z="0"/>
</O>

<!-- ❌ WRONG: Missing square brackets -->
<O T="Repeat" N="Points" S="0" E="10" CTRL="i" StaticParams="Spacing">
  ...
</O>

<!-- ✅ CORRECT: StaticParams with square brackets -->
<O T="Repeat" N="Points" S="0" E="10" CTRL="i" StaticParams="[Spacing]">
  <P N="Spacing" V="12"/>
  <O T="Point" X="i*Spacing" Y="0" Z="0"/>
</O>

<!-- ✅ CORRECT: Multiple static params -->
<O T="Repeat" N="Points" S="0" E="10" CTRL="i" StaticParams="[Spacing,Offset,Material]">
  <P N="Spacing" V="12"/>
  <P N="Offset" V="5"/>
  <O T="Point" X="i*Spacing+Offset" Y="0" Z="0"/>
</O>

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:

<!-- User's project (created 6 months ago): -->
<O N="MyObject" T="SomeWorkflowObject">
  <O N="InputGroup" T="Group">
    <P N="WidthOld" V="25"/>     <!-- User entered 25 -->
    <P N="HeightOld" V="30"/>    <!-- User entered 30 -->
  </O>
</O>

<!-- Developer renames parameters: -->
<!-- OLD: WidthOld, HeightOld -->
<!-- NEW: WidthNew, HeightNew -->

<!-- ❌ RESULT: User updates software version -->
<!-- WidthOld = 25 → LOST (falls back to default) -->
<!-- HeightOld = 30 → LOST (falls back to default) -->
<!-- User's values are silently ignored! -->

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:

<!-- DR Object Structure -->
<O N="MyDRObject" T="Project">
    <!-- User input parameters (DR interface) -->
    <O N="General" T="Group">
        <P N="userInput1" V="..." Role="Input" Category="General"/>
        <P N="userInput2" V="..." Role="Input" Category="General"/>
    </O>

    <!-- DesignRun group - maps to Base object -->
    <O N="STGLR" T="DesignRun">
        <P N="LibObjTypeName" V="OBPBase_MyObject" T="Text"/>
        <P N="LibObjVersion" V="1"/>

        <!-- Map ALL Base Role="Input" parameters here -->
        <P N="baseInputParam1" V="userInput1"/>
        <P N="baseInputParam2" V="userInput2"/>

        <!-- WARNING: Can also override non-Input parameters -->
        <P N="baseCalculatedParam" V="customValue"/>
    </O>
</O>

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:

<!-- Base Object -->
<O N="OBPBase_MyCodeCheck" T="Project">
    <P N="width" V="10" Role="Input"/>
    <P N="height" V="20" Role="Input"/>

    <!-- Internal calculation parameter - NOT an Input -->
    <P N="safety_factor" V="1.5"/>

    <P N="area" V="width * height"/>
    <P N="capacity" V="area * safety_factor"/>
    <P N="check1" V="capacity * safety_factor"/>
    <P N="check2" V="width * safety_factor"/>
</O>

<!-- DR Object - PROBLEMATIC -->
<O N="OBPDR_MyCodeCheck" T="Project">
    <P N="userWidth" V="15" Role="Input"/>
    <P N="userHeight" V="25" Role="Input"/>
    <P N="userFactor" V="2.0" Role="Input"/>

    <O N="Run" T="DesignRun">
        <P N="LibObjTypeName" V="OBPBase_MyCodeCheck" T="Text"/>

        <!-- OK: Map Input parameters -->
        <P N="width" V="userWidth"/>
        <P N="height" V="userHeight"/>

        <!-- ⚠️ PROBLEM: Overriding non-Input parameter -->
        <P N="safety_factor" V="userFactor"/>
        <!-- This overrides safety_factor EVERYWHERE in Base:
             - capacity calculation
             - check1 calculation
             - check2 calculation
             ALL will now use 2.0 instead of 1.5 -->
    </O>
</O>

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

   <!-- Fix in Base object -->
   <P N="safety_factor" V="1.5" Role="Input"/>

   • 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

<O N="STGLR" T="DesignRun">
    <P N="LibObjTypeName" V="OBPBase_MyObject" T="Text"/>
</O>

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

# Extract Base Role="Input" parameters
$baseLines = Get-Content 'OBPBase_MyObject.xml'
$baseInputs = @()
foreach ($line in $baseLines) {
    if ($line -match 'Role="Input"' -and $line -match '<P\s+N="([^"]+)"') {
        $baseInputs += $matches[1]
    }
}

Write-Host "Base object has $($baseInputs.Count) Role='Input' parameters"

# Extract DR DesignRun parameters
$drLines = Get-Content 'OBPDR_MyObject.xml'
$designRunStart = -1
$designRunEnd = -1

# Find DesignRun group boundaries
for ($i = 0; $i -lt $drLines.Count; $i++) {
    if ($drLines[$i] -match '<O\s+[^>]*T="DesignRun"') {
        $designRunStart = $i
    }
    if ($designRunStart -gt -1 -and $designRunEnd -eq -1 -and $drLines[$i] -match '^\s*</O>\s*$') {
        $designRunEnd = $i
        break
    }
}

# Extract DesignRun parameters
$drParams = @()
for ($i = $designRunStart; $i -le $designRunEnd; $i++) {
    if ($drLines[$i] -match '<P\s+N="([^"]+)"') {
        $drParams += $matches[1]
    }
}

Write-Host "DesignRun group has $($drParams.Count) parameters mapped"

# Find missing Input parameters
$missing = @()
foreach ($param in $baseInputs) {
    if ($drParams -notcontains $param) {
        $missing += $param
    }
}

# Report missing inputs
if ($missing.Count -eq 0) {
    Write-Host "`n✅ All Base Role='Input' parameters are mapped in DesignRun"
} else {
    Write-Host "`n❌ ERROR: Missing $($missing.Count) Role='Input' parameters in DesignRun:"
    foreach ($param in $missing) {
        for ($i = 0; $i -lt $baseLines.Count; $i++) {
            if ($baseLines[$i] -match "N=`"$param`"" -and $baseLines[$i] -match 'Role="Input"') {
                Write-Host "  - $param (Base line $($i + 1))"
                break
            }
        }
    }
}

# Check for non-Input parameter overrides
$drNonInputOverrides = @()
foreach ($param in $drParams) {
    if ($baseInputs -notcontains $param -and $param -ne 'LibObjTypeName' -and $param -ne 'LibObjVersion') {
        $drNonInputOverrides += $param
    }
}

if ($drNonInputOverrides.Count -gt 0) {
    Write-Host "`n⚠️  WARNING: $($drNonInputOverrides.Count) non-Input parameter(s) overridden:"
    $drNonInputOverrides | ForEach-Object { Write-Host "  - $_" }
    Write-Host "`nThese overrides are PROBLEMATIC because:"
    Write-Host "  1. They override internal Base object calculations"
    Write-Host "  2. They affect ALL occurrences of these parameters in Base"
    Write-Host "  3. They violate separation of data (DR) and logic (Base)"
    Write-Host "`nRECOMMENDATION:"
    Write-Host "  - If users need to control these parameters: Add Role='Input' to Base object"
    Write-Host "  - If parameters should remain internal: Remove these overrides from DR"
}

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:

<!-- WORKS: Sibling groups can access each other's parameters -->
<O N="CADDrawing" T="Group">
    <P N="SharedParam" V="10" />
    <O N="Drawing1" T="CADD">
        <!-- Can use SharedParam -->
    </O>
</O>
<O N="SectionGeometries" T="Group">
    <O N="Section1" T="Section">
        <P N="Value" V="SharedParam" />  <!-- ✅ WORKS (sibling group access) -->
    </O>
</O>

<!-- BETTER: Move shared parameters to parent level -->
<O N="SharedParameters" T="Group">
    <P N="SharedParam" V="10" />
</O>
<O N="CADDrawing" T="Group">
    <O N="Drawing1" T="CADD">
        <!-- Can use SharedParam -->
    </O>
</O>
<O N="SectionGeometries" T="Group">
    <O N="Section1" T="Section">
        <P N="Value" V="SharedParam" />  <!-- ✅ CLEARER (parent parameter) -->
    </O>
</O>

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