docs: Major documentation overhaul - restructure folders, update tagline, add Getting Started guide
- Restructure docs/ folder (remove numeric prefixes): - 04_USER_GUIDES -> guides/ - 05_API_REFERENCE -> api/ - 06_PHYSICS -> physics/ - 07_DEVELOPMENT -> development/ - 08_ARCHIVE -> archive/ - 09_DIAGRAMS -> diagrams/ - Replace tagline 'Talk, don't click' with 'LLM-driven optimization framework' in 9 files - Create comprehensive docs/GETTING_STARTED.md: - Prerequisites and quick setup - Project structure overview - First study tutorial (Claude or manual) - Dashboard usage guide - Neural acceleration introduction - Rewrite docs/00_INDEX.md with correct paths and modern structure - Archive obsolete files: - 01_PROTOCOLS.md -> archive/historical/01_PROTOCOLS_legacy.md - 03_GETTING_STARTED.md -> archive/historical/ - ATOMIZER_PODCAST_BRIEFING.md -> archive/marketing/ - Update timestamps to 2026-01-20 across all key files - Update .gitignore to exclude docs/generated/ - Version bump: ATOMIZER_CONTEXT v1.8 -> v2.0
This commit is contained in:
406
docs/api/NX_FILE_STRUCTURE_PROTOCOL.md
Normal file
406
docs/api/NX_FILE_STRUCTURE_PROTOCOL.md
Normal file
@@ -0,0 +1,406 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user