Export

Overview

This guide covers the Export object and its critical role in managing dependencies and scope when working with object instances.

Prerequisites: Read creating-instances.md first

What you'll learn:

Why Export exists and what goes in it
The Dependency Rule (critical!)
Instance scope (inside component vs in instance)
Why missing parameters = 0
Complex nested instances
Debugging export issues
Best practices

What is the Export Object?

The <O T="Export"> object controls what is accessible when someone creates an instance of your component.

Purpose:

Define the public interface of your component
Hide implementation details
Control what other components can access

Basic Structure

<O N="MyComponent" T="Project">
    <!-- Inputs -->
    <P N="input1" V="..." Role="Input" />
    
    <!-- Internal (private) -->
    <P N="internal_calc" V="..." />
    
    <!-- Public interface (accessible) -->
    <O T="Export">
        <P N="result" V="..." />
        <P N="status" V="..." />
    </O>
    
    <!-- Geometry (private) -->
    <O N="Geo" T="Volume">...</O>
</O>

The Dependency Rule ⚠️ CRITICAL

The most important rule when using Export:

Any parameter referenced by an exported parameter must also be exported (or be a Role="Input" parameter).

Why This Rule Exists

When you create an instance, exported parameters are copied to the instance. They lose access to non-exported parameters.

Missing parameters evaluate to 0, breaking calculations.

The Problem

Component definition:

<O N="BeamCheck" T="Project">
    <P N="load" V="1000" Role="Input" />
    
    <!-- Outside Export -->
    <P N="capacity" V="5000" />
    
    <O T="Export">
        <P N="utilization" V="load / capacity" />  <!-- ⚠️ Problem! -->
    </O>
</O>

Inside the component - works fine:

<P N="check" V="utilization" />  <!-- = 1000 / 5000 = 0.2 ✅ -->

In an instance - breaks:

<O N="MyBeam" T="BeamCheck">
    <P N="load" V="1000" />
    
    <!-- Exported parameter copied -->
    <P N="utilization" V="load / capacity" />  <!-- capacity not found → capacity = 0 → infinity! ❌ -->
</O>

<P N="check" V="MyBeam.utilization" />  <!-- = infinity ❌ -->

The Fix

Move all dependencies inside Export:

<O N="BeamCheck" T="Project">
    <P N="load" V="1000" Role="Input" />
    
    <O T="Export">
        <!-- Move capacity inside Export -->
        <P N="capacity" V="5000" />
        <P N="utilization" V="load / capacity" />  <!-- ✅ Works correctly -->
    </O>
</O>

Now works in instances:

<O N="MyBeam" T="BeamCheck">
    <P N="load" V="1000" />
    
    <P N="capacity" V="5000" />  <!-- ✅ Copied -->
    <P N="utilization" V="load / capacity" />  <!-- ✅ = 0.2 -->
</O>

<P N="check" V="MyBeam.utilization" />  <!-- ✅ = 0.2 -->

Instance Scope and Isolation

Understanding how scope works is critical for Export.

Two Different Contexts

Context

Can Access

Cannot Access

Inside component

Everything in component

Nothing

In instance

Inputs + Exports only

Non-exported parameters

Inside the Component

Parameters inside Export CAN access parameters outside Export:

<O N="Example" T="Project">
    <P N="input" V="10" Role="Input" />
    
    <!-- Outside Export -->
    <P N="constant" V="3.14" />
    <P N="factor" V="2.5" />
    
    <O T="Export">
        <P N="result1" V="input * constant" />  <!-- ✅ Works inside -->
        <P N="result2" V="input * factor" />    <!-- ✅ Works inside -->
    </O>
</O>

<!-- Using inside the component -->
<P N="r1" V="result1" />  <!-- = 10 * 3.14 = 31.4 ✅ -->
<P N="r2" V="result2" />  <!-- = 10 * 2.5 = 25 ✅ -->

In an Instance

Exported parameters are copied and isolated:

<O N="MyExample" T="Example">
    <P N="input" V="10" />
    
    <!-- Exported parameters copied -->
    <P N="result1" V="input * constant" />  <!-- constant not found → 0 ❌ -->
    <P N="result2" V="input * factor" />    <!-- factor not found → 0 ❌ -->
</O>

<P N="r1" V="MyExample.result1" />  <!-- = 10 * 0 = 0 ❌ -->
<P N="r2" V="MyExample.result2" />  <!-- = 10 * 0 = 0 ❌ -->

The parameters work inside the component but fail in instances!

Why This Happens

Instance is created
System copies inputs and exports to instance
Exported parameters no longer have access to the original component's internal parameters
Missing parameters → evaluate to 0
Calculations break

Chain of Dependencies

All levels of dependency must be exported.

Wrong: Incomplete Dependency Chain

<O N="Complex" T="Project">
    <P N="input" V="10" Role="Input" />
    
    <!-- Outside Export -->
    <P N="step1" V="input * 2" />
    <P N="step2" V="step1 + 5" />
    <P N="step3" V="step2 * 3" />
    
    <O T="Export">
        <P N="final" V="step3 + 10" />  <!-- ❌ step3 = 0 in instances -->
    </O>
</O>

In instance:

<O N="MyComplex" T="Complex">
    <P N="input" V="10" />
    <P N="final" V="step3 + 10" />  <!-- step3 = 0 → final = 10 (wrong!) ❌ -->
</O>

Right: Complete Dependency Chain

<O N="Complex" T="Project">
    <P N="input" V="10" Role="Input" />
    
    <O T="Export">
        <!-- Move entire chain inside Export -->
        <P N="step1" V="input * 2" />
        <P N="step2" V="step1 + 5" />
        <P N="step3" V="step2 * 3" />
        <P N="final" V="step3 + 10" />  <!-- ✅ Works -->
    </O>
</O>

In instance:

<O N="MyComplex" T="Complex">
    <P N="input" V="10" />
    <P N="step1" V="input * 2" />    <!-- ✅ = 20 -->
    <P N="step2" V="step1 + 5" />    <!-- ✅ = 25 -->
    <P N="step3" V="step2 * 3" />    <!-- ✅ = 75 -->
    <P N="final" V="step3 + 10" />   <!-- ✅ = 85 -->
</O>

What to Put in Export

✅ Put in Export

Calculated results users need:

<O T="Export">
    <P N="area" V="width * height" />
    <P N="volume" V="area * depth" />
    <P N="weight" V="volume * density" />
    <P N="density" V="2400" />  <!-- ← Also needed because weight uses it -->
</O>

Analysis results:

<O T="Export">
    <P N="max_stress" V="..." />
    <P N="max_deflection" V="..." />
    <P N="utilization" V="..." />
    <P N="allowable_stress" V="..." />  <!-- ← Dependency -->
</O>

Nested objects for external access:

<O T="Export">
    <O N="Girder" T="SteelGirder">
        <!-- ... -->
    </O>
    <P N="total_weight" V="Girder.weight * 4" />
</O>

Status/flags:

<O T="Export">
    <P N="passes_check" V="utilization .LT. 1.0" />
    <P N="warning" V="utilization .GT. 0.9" />
</O>

❌ Keep Outside Export

Geometry:

<!-- Outside Export -->
<O N="BeamGeo" T="Volume">
    <!-- Geometry is for visualization, not for external access -->
</O>

Intermediate calculations (if not needed externally):

<!-- Outside Export -->
<P N="temp_calc_1" V="..." />
<P N="temp_calc_2" V="..." />

<O T="Export">
    <!-- Only export final result -->
    <P N="final_result" V="temp_calc_1 + temp_calc_2" />  <!-- ❌ Problem! -->
</O>

BUT: If exported parameters reference them, they must be in Export!

Implementation details:

<!-- Outside Export -->
<P N="internal_flag" V="1" />
<P N="debug_value" V="..." />

Complex Nested Instances

When instances contain instances, Export becomes crucial.

Example: House Using Cube

Cube component:

<O N="Cube" T="Project">
    <P N="cube_x" V="0" Role="Input" />
    <P N="cube_y" V="0" Role="Input" />
    <P N="cube_side" V="60" Role="Input" />
    
    <O T="Export">
        <P N="cube_area" V="cube_side * cube_side" />
        <P N="cube_volume" V="cube_area * cube_side" />
        
        <O N="Coordinates" T="Group">
            <P N="center_bottom" V="[cube_x, cube_y, 0]" />
            <P N="center_top" V="translate(center_bottom, 0, 0, cube_side)" />
        </O>
    </O>
    
    <O N="CubeGeo" T="Volume" X="cube_x" Y="cube_y">
        <!-- ... -->
    </O>
</O>

House component:

<O N="House" T="Project">
    <P N="center_x" V="0" Role="Input" />
    <P N="center_y" V="0" Role="Input" />
    <P N="height" V="200" Role="Input" />
    <P N="side_length" V="60" Role="Input" />
    
    <O T="Export">
        <!-- House_Base instance INSIDE Export -->
        <O N="House_Base" T="Cube">
            <P N="cube_x" V="center_x" />
            <P N="cube_y" V="center_y" />
            <P N="cube_side" V="side_length" />
            <O N="Coordinates" T="Group" Exported="1">
                <P N="center_bottom" V="[cube_x, cube_y, 0]" />
                <P N="center_top" V="translate(center_bottom, 0, 0, cube_side)" />
            </O>
            <P N="cube_area" V="cube_side * cube_side" />
            <P N="cube_volume" V="cube_area * cube_side" />
        </O>
        
        <!-- Can reference House_Base exports -->
        <P N="triangle_height" V="height - House_Base.cube_side" />
        <P N="triangle_volume" V="triangle_height * side_length * side_length / 2" />
        <P N="total_volume" V="triangle_volume + House_Base.cube_volume" />
    </O>
    
    <!-- Roof geometry - outside Export -->
    <P N="roof_base" V="House_Base.Coordinates.center_top" />
    <O T="Volume" X="roof_base[0]" Y="roof_base[1]" Z="roof_base[2]">
        <!-- ... -->
    </O>
</O>

Instance of House:

<O N="MyHouse" T="House">
    <P N="center_x" V="0" />
    <P N="height" V="200" />
    <P N="side_length" V="60" />
    
    <!-- House_Base appears -->
    <O N="House_Base" T="Cube" Exported="1">
        <P N="cube_x" V="center_x" />
        <P N="cube_y" V="center_y" />
        <P N="cube_side" V="side_length" />
        <O N="Coordinates" T="Group" Exported="1">
            <P N="center_bottom" V="[cube_x, cube_y, 0]" />
            <P N="center_top" V="translate(center_bottom, 0, 0, cube_side)" />
        </O>
        <P N="cube_area" V="cube_side * cube_side" />
        <P N="cube_volume" V="cube_area * cube_side" />
    </O>
    
    <P N="triangle_height" V="height - House_Base.cube_side" />
    <P N="triangle_volume" V="triangle_height * side_length * side_length / 2" />
    <P N="total_volume" V="triangle_volume + House_Base.cube_volume" />
</O>

Access nested values:

<P N="vol" V="MyHouse.total_volume" />                      <!-- ✅ Works -->
<P N="base_vol" V="MyHouse.House_Base.cube_volume" />       <!-- ✅ Works -->
<P N="top_coord" V="MyHouse.House_Base.Coordinates.center_top" /> <!-- ✅ Works -->

What If House_Base Wasn't Exported?

House without exporting House_Base:

<O N="BadHouse" T="Project">
    <P N="side_length" V="60" Role="Input" />
    
    <!-- House_Base OUTSIDE Export -->
    <O N="House_Base" T="Cube">
        <P N="cube_side" V="side_length" />
        <P N="cube_area" V="cube_side * cube_side" />
        <P N="cube_volume" V="cube_area * cube_side" />
    </O>
    
    <O T="Export">
        <P N="total_volume" V="House_Base.cube_volume + 100" />  <!-- Works internally -->
    </O>
</O>

Instance:

<O N="MyBadHouse" T="BadHouse">
    <P N="side_length" V="60" />
    
    <!-- House_Base does NOT appear -->
    <P N="total_volume" V="House_Base.cube_volume + 100" />  <!-- House_Base = 0 → 0 + 100 = 100 ❌ -->
</O>

Problems:

<P N="vol" V="MyBadHouse.total_volume" />              <!-- = 100 (wrong!) ❌ -->
<P N="base" V="MyBadHouse.House_Base.cube_volume" />   <!-- Fails ❌ -->

Common Mistakes

❌ Mistake 1: Missing Simple Dependency

<O N="BadExample" T="Project">
    <P N="width" V="100" Role="Input" />
    <P N="height" V="50" />  <!-- Not input, not exported -->
    
    <O T="Export">
        <P N="area" V="width * height" />  <!-- ❌ height = 0 in instances -->
    </O>
</O>

Instance:

<O N="My" T="BadExample">
    <P N="width" V="100" />
    <P N="area" V="width * height" />  <!-- height = 0 → area = 0 ❌ -->
</O>

Fix:

<O T="Export">
    <P N="height" V="50" />  <!-- ✅ Move inside -->
    <P N="area" V="width * height" />
</O>

❌ Mistake 2: Partial Dependency Chain

<O N="BadChain" T="Project">
    <P N="input" V="10" Role="Input" />
    
    <!-- Outside Export, not input -->
    <P N="a" V="input * 2" />
    
    <O T="Export">
        <P N="b" V="a + 5" />    <!-- ❌ a = 0 in instances -->
        <P N="c" V="b * 2" />    <!-- Uses wrong b value -->
    </O>
</O>

In instance:

<O N="MyChain" T="BadChain">
    <P N="input" V="10" />
    
    <!-- Exported parameters -->
    <P N="b" V="a + 5" />    <!-- a = 0 → b = 5 (wrong!) ❌ -->
    <P N="c" V="b * 2" />    <!-- c = 10 (wrong!) ❌ -->
</O>

Fix:

<O N="GoodChain" T="Project">
    <P N="input" V="10" Role="Input" />
    
    <O T="Export">
        <P N="a" V="input * 2" />  <!-- ✅ Move inside -->
        <P N="b" V="a + 5" />
        <P N="c" V="b * 2" />
    </O>
</O>

❌ Mistake 3: Not Exporting Nested Object

<O N="BadNesting" T="Project">
    <!-- Nested object outside Export -->
    <O N="SubComponent" T="SomeType">
        <P N="value" V="100" />
    </O>
    
    <O T="Export">
        <P N="total" V="SubComponent.value + 50" />  <!-- Works internally -->
    </O>
</O>

Instance:

<O N="My" T="BadNesting">
    <P N="total" V="SubComponent.value + 50" />  <!-- SubComponent = 0 → total = 50 ❌ -->
</O>

<P N="sub" V="My.SubComponent.value" />  <!-- Fails ❌ -->

Fix:

<O T="Export">
    <O N="SubComponent" T="SomeType">  <!-- ✅ Move inside -->
        <P N="value" V="100" />
    </O>
    <P N="total" V="SubComponent.value + 50" />
</O>

❌ Mistake 4: Over-Exporting (Anti-pattern)

<O T="Export">
    <!-- Exporting everything! -->
    <P N="temp1" V="..." />
    <P N="temp2" V="..." />
    <P N="debug_x" V="..." />
    <P N="internal_flag" V="..." />
    <P N="calc_step_1" V="..." />
    <P N="calc_step_2" V="..." />
    <!-- ... 50 more ... -->
    <P N="actual_result" V="..." />
</O>

Problems:

❌ Cluttered interface
❌ Exposes implementation details
❌ Hard to refactor
❌ Confusing for users

✅ Better - Export only what final results depend on:

<O N="BeamAnalysis" T="Project">
    <P N="length" V="1000" Role="Input" />
    <P N="load" V="50" Role="Input" />
    
    <!-- Internal calculations - NOT needed by exported results -->
    <P N="debug_flag" V="1" />
    <P N="temp_var" V="load * 2" />
    
    <O T="Export">
        <!-- Export dependencies needed by final results -->
        <P N="load_factor" V="1.5" />
        <P N="resistance_factor" V="0.9" />
        <P N="material_strength" V="250" />
        
        <P N="capacity" V="material_strength * resistance_factor" />
        <P N="demand" V="load * length * length / 8 * load_factor" />
        
        <!-- Final results -->
        <P N="utilization" V="demand / capacity" />
        <P N="passes" V="utilization .LT. 1.0" />
    </O>
</O>

In this example:

❌ debug_flag, temp_var - NOT exported (not used by exported results)
✅ load_factor, resistance_factor, material_strength - Exported (used by capacity and demand)
✅ capacity, demand - Exported (used by utilization)
✅ utilization, passes - Exported (final results)

In this example:

❌ load_factor, resistance_factor, material_strength - NOT exported (internal only)
✅ capacity, demand - Exported (needed by utilization)
✅ utilization, passes - Exported (final results)

Debugging Export Issues

Problem: Calculation works in component but returns 0 or wrong value in instance

Diagnosis: Missing dependency

Steps:

Find the exported parameter with wrong value
Look at its formula
Check each parameter referenced:
- Is it inside Export? ✅
- Does it have Role="Input"? ✅
- If neither → That's the problem
Move missing dependency inside Export

Example:

<!-- Component -->
<P N="capacity" V="5000" />  <!-- Outside Export ← PROBLEM -->
<O T="Export">
    <P N="ratio" V="load / capacity" />
</O>

<!-- Instance -->
<O N="My" T="Component">
    <P N="ratio" V="load / capacity" />  <!-- capacity = 0 → infinity -->
</O>

<!-- Fix -->
<O T="Export">
    <P N="capacity" V="5000" />  <!-- ✅ Move inside -->
    <P N="ratio" V="load / capacity" />
</O>

Problem: Can't access nested object

Diagnosis: Nested object not in Export

Steps:

Find where nested object is defined
Check if it's inside <O T="Export">
If outside → move it inside Export

Example:

<!-- Wrong -->
<O N="SubObj" T="Type" />  <!-- Outside Export ← PROBLEM -->
<O T="Export">
    <P N="value" V="SubObj.param" />
</O>

<!-- Can't access -->
<P N="x" V="Instance.SubObj.param" />  <!-- ❌ Fails -->

<!-- Fix -->
<O T="Export">
    <O N="SubObj" T="Type" />  <!-- ✅ Move inside -->
    <P N="value" V="SubObj.param" />
</O>

Problem: Value is infinity or NaN

Diagnosis: Division by zero - missing parameter evaluates to 0

Steps:

Find the division operation
Check if denominator is:
- Inside Export ✅
- Has Role="Input" ✅
- If neither → That's the problem

Example:

<P N="capacity" V="5000" />  <!-- Outside ← PROBLEM -->
<O T="Export">
    <P N="ratio" V="demand / capacity" />  <!-- capacity = 0 → infinity -->
</O>

Problem: Instance seems to have old/wrong values

Diagnosis: Dependencies changed but not updated in Export

Steps:

Check if all dependencies are in Export
Verify formulas are correct
Check if intermediate values need to be exported

Best Practices

1. Always Export Dependencies

Rule: If parameter X references parameter Y, both must be exported (or Y must be input).

<!-- ✅ Good -->
<O T="Export">
    <P N="capacity" V="5000" />
    <P N="demand" V="1000" />
    <P N="ratio" V="demand / capacity" />
</O>

<!-- ❌ Bad -->
<P N="capacity" V="5000" />  <!-- Outside -->
<O T="Export">
    <P N="ratio" V="demand / capacity" />  <!-- ❌ capacity missing -->
</O>

2. Test with Instances

Always create test instances:

<!-- Define component -->
<O N="MyComponent" T="Project">
    <!-- ... -->
</O>

<!-- Test instance -->
<O N="TestInstance" T="MyComponent">
    <P N="param1" V="100" />
</O>

<!-- Verify exported values work -->
<P N="test1" V="TestInstance.exported_value" />
<P N="test2" V="TestInstance.NestedObj.value" />

If test fails → fix Export dependencies

3. Minimize Export Surface

Only export what's truly needed:

<!-- ❌ Bad - exports too much -->
<O T="Export">
    <P N="temp_var" V="..." />
    <P N="debug_value" V="..." />
    <P N="intermediate_1" V="..." />
    <P N="intermediate_2" V="..." />
    <P N="final_result" V="..." />
</O>

<!-- ✅ Good - clean interface -->
<O T="Export">
    <!-- Only dependencies needed by exported values -->
    <P N="intermediate_sum" V="..." />
    <!-- Final result -->
    <P N="final_result" V="intermediate_sum * 2" />
</O>

4. Document Exported Parameters

<O T="Export">
    <P N="utilization" V="..." 
       D="Demand/capacity ratio (0.0 = no load, 1.0 = at capacity, >1.0 = over capacity)" />
    <P N="passes" V="utilization .LT. 1.0" 
       D="Does component pass check? [1=Yes, 0=No]" />
</O>

<O T="Export">
    <!-- Geometry -->
    <P N="area" V="..." />
    <P N="volume" V="..." />
    
    <!-- Nested components -->
    <O N="Girder" T="SteelGirder">...</O>
    <O N="Deck" T="Deck">...</O>
    
    <!-- Analysis -->
    <P N="max_stress" V="..." />
    <P N="utilization" V="..." />
    
    <!-- Status -->
    <P N="passes" V="..." />
</O>

6. Trace Dependency Chains

When exporting calculated values, trace all dependencies:

<!-- Find all dependencies -->
<P N="result" V="a + b * c" />
<!-- Needs: a, b, c -->

<!-- Check each -->
<P N="a" V="input1 * 2" />      <!-- Needs: input1 -->
<P N="b" V="input2 + constant" /> <!-- Needs: input2, constant -->
<P N="c" V="factor" />           <!-- Needs: factor -->

<!-- Export all -->
<O T="Export">
    <P N="constant" V="3.14" />
    <P N="factor" V="2.5" />
    <P N="a" V="input1 * 2" />
    <P N="b" V="input2 + constant" />
    <P N="c" V="factor" />
    <P N="result" V="a + b * c" />
</O>

7. Use Meaningful Export Names

<!-- ✅ Good -->
<O T="Export">
    <P N="max_stress_mpa" V="..." />
    <P N="utilization_ratio" V="..." />
    <P N="passes_strength_check" V="..." />
</O>

<!-- ❌ Bad -->
<O T="Export">
    <P N="val1" V="..." />
    <P N="x" V="..." />
    <P N="flag" V="..." />
</O>

Summary

Critical Rules

Dependency Rule: Exported parameters must only reference:
- Other exported parameters
- Input parameters (Role="Input")
Missing Parameters = 0: Non-exported parameters evaluate to 0 in instances
Scope Isolation: Instances cannot access non-exported parameters
Test with Instances: Working inside ≠ working in instances
Export Nested Objects: For external access, nested instances must be in Export

Quick Checklist

When creating Export:

All dependencies inside Export or are inputs?
Nested objects that need external access inside Export?
Tested with actual instance?
Exported parameters have descriptions?
Only exporting what's needed (not over-exporting)?

PreviousComponent Instances NextExtends

Last updated 7 months ago

Good afternoon

Overview

What is the Export Object?

Basic Structure

The Dependency Rule ⚠️ CRITICAL

Why This Rule Exists

The Problem

The Fix

Instance Scope and Isolation

Two Different Contexts

Inside the Component

In an Instance

Why This Happens

Chain of Dependencies

Wrong: Incomplete Dependency Chain

Right: Complete Dependency Chain

What to Put in Export

✅ Put in Export

❌ Keep Outside Export

Complex Nested Instances

Example: House Using Cube

What If House_Base Wasn't Exported?

Common Mistakes

❌ Mistake 1: Missing Simple Dependency

❌ Mistake 2: Partial Dependency Chain

❌ Mistake 3: Not Exporting Nested Object

❌ Mistake 4: Over-Exporting (Anti-pattern)

Debugging Export Issues

Problem: Calculation works in component but returns 0 or wrong value in instance

Problem: Can't access nested object

Problem: Value is infinity or NaN

Problem: Instance seems to have old/wrong values

Best Practices

1. Always Export Dependencies

2. Test with Instances

3. Minimize Export Surface

4. Document Exported Parameters

5. Group Related Exports

6. Trace Dependency Chains

7. Use Meaningful Export Names

Summary

Critical Rules

Quick Checklist