# 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

```xml
<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:**

```xml
<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:**

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

**In an instance - breaks:**

```xml
<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:**

```xml
<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:**

```xml
<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:

```xml
<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**:

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

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

***

## Chain of Dependencies

**All levels of dependency must be exported.**

### Wrong: Incomplete Dependency Chain

```xml
<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:**

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

```xml
<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:**

```xml
<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:**

```xml
<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:**

```xml
<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:**

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

**Status/flags:**

```xml
<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:**

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

**Intermediate calculations (if not needed externally):**

```xml
<!-- 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:**

```xml
<!-- 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:**

```xml
<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:**

```xml
<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:**

```xml
<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:**

```xml
<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:**

```xml
<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:**

```xml
<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:**

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

```xml
<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:**

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

**Fix:**

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

### ❌ Mistake 2: Partial Dependency Chain

```xml
<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:**

```xml
<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:**

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

```xml
<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:**

```xml
<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:**

```xml
<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)

```xml
<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:**

```xml
<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:**

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

**Example:**

```xml
<!-- 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:**

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

**Example:**

```xml
<!-- 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:**

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

**Example:**

```xml
<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:**

1. Check if all dependencies are in Export
2. Verify formulas are correct
3. 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).

```xml
<!-- ✅ 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:

```xml
<!-- 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:

```xml
<!-- ❌ 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

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

### 5. Group Related Exports

```xml
<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:

```xml
<!-- 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

```xml
<!-- ✅ 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

1. **Dependency Rule:** Exported parameters must only reference:
   * Other exported parameters
   * Input parameters (`Role="Input"`)
2. **Missing Parameters = 0:** Non-exported parameters evaluate to 0 in instances
3. **Scope Isolation:** Instances cannot access non-exported parameters
4. **Test with Instances:** Working inside ≠ working in instances
5. **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)?

***