Atomizer/docs/api/NX_FILE_STRUCTURE_PROTOCOL.md

# NX File Structure Protocol for Atomizer Studies

## Overview

This document defines the **mandatory file structure** for all NX Simcenter optimization studies. Following this protocol ensures optimization runs succeed without manual intervention.

## File Types and Purposes

### Part Files (.prt)

**Master Geometry File**: `<ModelName>.prt`
- Contains parametric CAD geometry
- Design variables are NX expressions
- Primary file opened by NX during optimization

**Idealized Part File**: `<ModelName>_fem<N>_i.prt`
- Auto-generated by NX during FEM idealization
- Contains simplified geometry for meshing
- Required for mesh regeneration
- MUST be copied with the study

**Assembly Part File** (for assemblies): `<AssemblyName>.prt`
- Top-level assembly structure
- References component parts
- Contains assembly constraints

### FEM Files (.fem)

**Part-Level FEM**: `<ModelName>_fem<N>.fem`
- Mesh definition for single part
- Material properties
- Boundary conditions
- Mesh parameters

**Assembly FEM** (.afem): `<AssemblyName>_fem<N>.afem`
- Assembly-level FEM structure
- Component FEM references
- Contact definitions
- Assembly-level boundary conditions
- **Requires all component .fem files**

### Simulation Files (.sim)

**Simulation Setup**: `<ModelName>_sim<N>.sim`
- Solution definitions (SOL 101, 103, etc.)
- Load cases
- Analysis types (static, modal, buckling, etc.)
- Results configuration
- References FEM file(s)

---

## Mandatory File Sets

### SINGLE PART ANALYSIS

**REQUIRED FILES** (All 4 must be present):

```
1_setup/model/
├── <ModelName>.prt              # Master geometry (parametric)
├── <ModelName>_fem1.fem         # FEM mesh definition
├── <ModelName>_fem1_i.prt       # Idealized geometry (CRITICAL!)
└── <ModelName>_sim1.sim         # Simulation setup
```

**Example** (Beam Study):
```
1_setup/model/
├── Beam.prt
├── Beam_fem1.fem
├── Beam_fem1_i.prt   ← Don't forget this!
└── Beam_sim1.sim
```

**Why _i.prt is Required**:
- NX needs it to regenerate mesh when parameters change
- Without it: "Unable to find idealized body" error
- Generated once, reused for all trials
- Must be version-controlled with study

---

### ASSEMBLY ANALYSIS

**REQUIRED FILES** (More complex):

```
1_setup/model/
├── <Assembly>.prt                    # Top assembly
├── <Assembly>_fem1.afem              # Assembly FEM (references below)
├── <Assembly>_sim1.sim               # Simulation setup
│
├── components/                        # Component parts subdirectory
│   ├── <Component1>.prt              # Component part
│   ├── <Component1>_fem1.fem         # Component FEM
│   ├── <Component1>_fem1_i.prt       # Component idealized part
│   │
│   ├── <Component2>.prt
│   ├── <Component2>_fem1.fem
│   ├── <Component2>_fem1_i.prt
│   │
│   └── ...                            # Additional components
```

**Example** (Bracket Assembly with 3 components):
```
1_setup/model/
├── BracketAssembly.prt
├── BracketAssembly_fem1.afem
├── BracketAssembly_sim1.sim
│
└── components/
    ├── Bracket.prt
    ├── Bracket_fem1.fem
    ├── Bracket_fem1_i.prt
    │
    ├── Plate.prt
    ├── Plate_fem1.fem
    ├── Plate_fem1_i.prt
    │
    ├── Bolt.prt
    ├── Bolt_fem1.fem
    └── Bolt_fem1_i.prt
```

---

## File Naming Conventions

### Standard Naming Pattern

```
<BaseName>_<FileType><Index>.<extension>

BaseName:   Model/assembly name (e.g., "Beam", "BracketAssembly")
FileType:   fem, sim
Index:      Sequential number (1, 2, 3, ...)
Extension:  .fem, .afem, .sim, .prt
```

### Examples

**Good**:
- `Beam_fem1.fem` → First FEM file for Beam
- `Beam_fem1_i.prt` → Idealized part for Beam FEM #1
- `Beam_sim1.sim` → First simulation for Beam
- `BracketAssembly_fem1.afem` → Assembly FEM

**Bad**:
- `BeamFEM.fem` → Missing index
- `Beam fem 1.fem` → Spaces not allowed
- `beam_fem1.fem` → Inconsistent capitalization
- `Beam_idealized.prt` → Non-standard naming

---

## Assembly FEM (.afem) Structure

### What Goes in .afem vs .fem

**Assembly FEM (.afem)**:
- References to component .fem files
- Contact pairs between components
- Assembly-level boundary conditions
- Component positioning/orientation
- Assembly-level loads
- Glue/weld connections

**Component FEM (.fem)**:
- Individual component mesh
- Component material properties
- Component-specific boundary conditions
- Local mesh refinement
- Component-specific loads

### Assembly FEM Dependencies

**Critical**: `.afem` file MUST have:
1. All referenced component `.prt` files
2. All referenced component `.fem` files
3. All referenced component `_i.prt` files
4. Proper relative paths to components directory

**Path Configuration**:
```
# In .afem file, component references should use:
./components/<Component>.prt
./components/<Component>_fem1.fem
```

---

## Study Directory Structure

### Complete Single-Part Study

```
study_name/
├── 1_setup/
│   ├── model/
│   │   ├── <Model>.prt           ← Master geometry
│   │   ├── <Model>_fem1.fem      ← FEM definition
│   │   ├── <Model>_fem1_i.prt    ← Idealized part (REQUIRED!)
│   │   └── <Model>_sim1.sim      ← Simulation setup
│   ├── optimization_config.json
│   └── workflow_config.json
│
├── 2_results/
│   └── (generated during optimization)
│
└── run_optimization.py
```

### Complete Assembly Study

```
study_name/
├── 1_setup/
│   ├── model/
│   │   ├── <Assembly>.prt
│   │   ├── <Assembly>_fem1.afem
│   │   ├── <Assembly>_sim1.sim
│   │   │
│   │   └── components/
│   │       ├── <Comp1>.prt
│   │       ├── <Comp1>_fem1.fem
│   │       ├── <Comp1>_fem1_i.prt
│   │       ├── <Comp2>.prt
│   │       ├── <Comp2>_fem1.fem
│   │       ├── <Comp2>_fem1_i.prt
│   │       └── ...
│   │
│   ├── optimization_config.json
│   └── workflow_config.json
│
├── 2_results/
└── run_optimization.py
```

---

## Common Errors and Solutions

### Error: "Unable to find idealized body"

**Cause**: Missing `_fem1_i.prt` file
**Solution**: Always copy the `_i.prt` file with your study

### Error: "Cannot open FEM file"

**Cause**: FEM file references missing component
**Solution**: Verify all component `.fem` and `.prt` files are present

### Error: "Mesh regeneration failed"

**Cause**: Idealized part doesn't match current geometry
**Solution**: Regenerate idealization in NX, copy new `_i.prt`

### Error: "Component not found in assembly"

**Cause**: Wrong path to components directory
**Solution**: Ensure `components/` subdirectory structure is correct

---

## Validation Checklist

### Before Creating Study

**Single Part**:
- [ ] `<Model>.prt` exists
- [ ] `<Model>_fem1.fem` exists
- [ ] `<Model>_fem1_i.prt` exists (CRITICAL!)
- [ ] `<Model>_sim1.sim` exists
- [ ] All 4 files in same directory

**Assembly**:
- [ ] `<Assembly>.prt` exists
- [ ] `<Assembly>_fem1.afem` exists
- [ ] `<Assembly>_sim1.sim` exists
- [ ] `components/` directory exists
- [ ] Each component has `.prt`, `.fem`, `_i.prt`
- [ ] All component paths in `.afem` are correct

### After Copying Study

**Run Quick Test**:
1. Open `<Model>.prt` in NX
2. Open Simulation Navigator
3. Solve simulation manually
4. If it solves → files are correct
5. If it fails → check error for missing files

---

## Best Practices

### 1. Always Copy Complete File Sets

Don't copy just `.prt` and `.sim`:
```bash
# Bad
cp Model.prt new_study/
cp Model_sim1.sim new_study/

# Good
cp Model.prt Model_fem1.fem Model_fem1_i.prt Model_sim1.sim new_study/
```

### 2. Preserve Directory Structure

For assemblies, maintain the `components/` structure:
```bash
# Create structure first
mkdir -p new_study/1_setup/model/components

# Then copy files
cp Assembly* new_study/1_setup/model/
cp components/* new_study/1_setup/model/components/
```

### 3. Version Control All Files

In git, track:
- All `.prt` files (including `_i.prt`)
- All `.fem` and `.afem` files
- All `.sim` files
- Do NOT use `.gitignore` to exclude `_i.prt`!

### 4. Document Component Dependencies

For assemblies, create a `COMPONENTS.md`:
```markdown
# Assembly Components

Main Assembly: BracketAssembly.prt

Components:
1. Bracket.prt - Main structural member (parametric)
2. Plate.prt - Mounting plate (parametric)
3. Bolt.prt - M6 bolt (fixed geometry)

Contact Pairs:
- Bracket <-> Plate: Bonded contact
- Bolt <-> Bracket: Frictional (μ=0.3)
```

---

## Advanced: Multi-Solution Studies

For studies with multiple analysis types (static + modal, etc.):

```
1_setup/model/
├── Model.prt
├── Model_fem1.fem              # Shared mesh
├── Model_fem1_i.prt            # Shared idealization
├── Model_sim1.sim              # Static analysis
└── Model_sim2.sim              # Modal analysis
```

Both `.sim` files reference the same `.fem` and `_i.prt`.

---

## Quick Reference Card

**Minimum Files for Single Part**:
```
✓ <Model>.prt
✓ <Model>_fem1.fem
✓ <Model>_fem1_i.prt   ← Don't forget!
✓ <Model>_sim1.sim
```

**Minimum Files for Assembly**:
```
✓ <Assembly>.prt
✓ <Assembly>_fem1.afem
✓ <Assembly>_sim1.sim
✓ components/<Comp1>.prt
✓ components/<Comp1>_fem1.fem
✓ components/<Comp1>_fem1_i.prt
(repeat for each component)
```

**Golden Rule**: If NX created it during meshing/simulation setup, you need to copy it for optimization!

---

## Future Enhancements

Planned protocol additions:
- [ ] Multi-mesh assembly support
- [ ] Submodeling workflows
- [ ] Contact table definitions
- [ ] Result mesh specification
- [ ] Optimization-specific mesh controls

---

**Last Updated**: 2025-01-22
**Version**: 1.0
**Status**: MANDATORY for all studies