Atomizer/docs/05_API_REFERENCE/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:

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

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

# 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