Atomizer/atomizer-field/README.md

AtomizerField Neural Field Data Parser

Version 1.0.0

A production-ready Python parser that converts NX Nastran FEA results into standardized neural field training data for the AtomizerField optimization platform.

What This Does

Instead of extracting just scalar values (like maximum stress) from FEA results, this parser captures complete field data - stress, displacement, and strain at every node and element. This enables neural networks to learn the physics of how structures respond to loads, enabling 1000x faster optimization with true physics understanding.

Features

• ✅ Complete Field Extraction: Captures displacement, stress, strain at ALL points
• ✅ Future-Proof Format: Versioned data structure (v1.0) designed for years of neural network training
• ✅ Efficient Storage: Uses HDF5 for large arrays, JSON for metadata
• ✅ Robust Parsing: Handles mixed element types (solid, shell, beam, rigid)
• ✅ Data Validation: Built-in physics and quality checks
• ✅ Batch Processing: Process hundreds of cases automatically
• ✅ Production Ready: Error handling, logging, provenance tracking

Quick Start

1. Installation

# Install dependencies
pip install -r requirements.txt

2. Prepare Your NX Nastran Analysis

In NX:

1. Create geometry and generate mesh
2. Apply materials (MAT1 cards)
3. Define boundary conditions (SPC)
4. Apply loads (FORCE, PLOAD4, GRAV)
5. Run SOL 101 (Linear Static)
6. Request output: DISPLACEMENT=ALL, STRESS=ALL, STRAIN=ALL

3. Organize Files

mkdir training_case_001
mkdir training_case_001/input
mkdir training_case_001/output

# Copy files
cp your_model.bdf training_case_001/input/model.bdf
cp your_model.op2 training_case_001/output/model.op2

4. Run Parser

# Parse single case
python neural_field_parser.py training_case_001

# Validate results
python validate_parsed_data.py training_case_001

5. Check Output

You'll get:

• neural_field_data.json - Complete metadata and structure
• neural_field_data.h5 - Large arrays (mesh, field results)

Usage Guide

Single Case Parsing

python neural_field_parser.py <case_directory>

Expected directory structure:

training_case_001/
├── input/
│   ├── model.bdf          # Nastran input deck
│   └── model.sim          # (optional) NX simulation file
├── output/
│   ├── model.op2          # Binary results (REQUIRED)
│   └── model.f06          # (optional) ASCII results
└── metadata.json          # (optional) Your design annotations

Output:

training_case_001/
├── neural_field_data.json  # Metadata, structure, small arrays
└── neural_field_data.h5    # Large arrays (coordinates, fields)

Batch Processing

Process multiple cases at once:

python batch_parser.py ./training_data

Expected structure:

training_data/
├── case_001/
│   ├── input/model.bdf
│   └── output/model.op2
├── case_002/
│   ├── input/model.bdf
│   └── output/model.op2
└── case_003/
    ├── input/model.bdf
    └── output/model.op2

Options:

# Skip validation (faster)
python batch_parser.py ./training_data --no-validate

# Stop on first error
python batch_parser.py ./training_data --stop-on-error

Output:

• Parses all cases
• Validates each one
• Generates batch_processing_summary.json with results

Data Validation

python validate_parsed_data.py training_case_001

Checks:

• ✓ File existence and format
• ✓ Data completeness (all required fields)
• ✓ Physics consistency (equilibrium, units)
• ✓ Data quality (no NaN/inf, reasonable values)
• ✓ Mesh integrity
• ✓ Material property validity

Data Structure v1.0

The parser produces a standardized data structure designed to be future-proof:

{
  "metadata": {
    "version": "1.0.0",
    "created_at": "timestamp",
    "analysis_type": "SOL_101",
    "units": {...}
  },
  "mesh": {
    "statistics": {
      "n_nodes": 15432,
      "n_elements": 8765
    },
    "nodes": {
      "ids": [...],
      "coordinates": "stored in HDF5"
    },
    "elements": {
      "solid": [...],
      "shell": [...],
      "beam": [...]
    }
  },
  "materials": [...],
  "boundary_conditions": {
    "spc": [...],
    "mpc": [...]
  },
  "loads": {
    "point_forces": [...],
    "pressure": [...],
    "gravity": [...],
    "thermal": [...]
  },
  "results": {
    "displacement": "stored in HDF5",
    "stress": "stored in HDF5",
    "strain": "stored in HDF5",
    "reactions": "stored in HDF5"
  }
}

HDF5 Structure

Large numerical arrays are stored in HDF5 for efficiency:

neural_field_data.h5
├── mesh/
│   ├── node_coordinates    [n_nodes, 3]
│   └── node_ids            [n_nodes]
└── results/
    ├── displacement        [n_nodes, 6]
    ├── displacement_node_ids
    ├── stress/
    │   ├── ctetra_stress/
    │   │   ├── data        [n_elem, n_components]
    │   │   └── element_ids
    │   └── cquad4_stress/...
    ├── strain/...
    └── reactions/...

Adding Design Metadata

Create a metadata.json in each case directory to track design parameters:

{
  "design_parameters": {
    "thickness": 2.5,
    "fillet_radius": 5.0,
    "rib_height": 15.0
  },
  "optimization_context": {
    "objectives": ["minimize_weight", "minimize_stress"],
    "constraints": ["max_displacement < 2mm"],
    "iteration": 42
  },
  "notes": "Baseline design with standard loading"
}

See metadata_template.json for a complete template.

Preparing NX Nastran Analyses

Required Output Requests

Add these to your Nastran input deck or NX solution setup:

DISPLACEMENT = ALL
STRESS = ALL
STRAIN = ALL
SPCFORCES = ALL

Recommended Settings

• Element Types: CTETRA10, CHEXA20, CQUAD4
• Analysis: SOL 101 (Linear Static) initially
• Units: Consistent (recommend SI: mm, N, MPa, kg)
• Output Format: OP2 (binary) for efficiency

Common Issues

"OP2 has no results"

• Ensure analysis completed successfully (check .log file)
• Verify output requests (DISPLACEMENT=ALL, STRESS=ALL)
• Check that OP2 file is not empty (should be > 1 KB)

"Can't find BDF nodes"

• Use .bdf or .dat file, not .sim
• Ensure mesh was exported to solver deck
• Check that BDF contains GRID cards

"Memory error with large models"

• Parser uses HDF5 chunking and compression
• For models > 100k elements, ensure you have sufficient RAM
• Consider splitting into subcases

Loading Parsed Data

In Python

import json
import h5py
import numpy as np

# Load metadata
with open("neural_field_data.json", 'r') as f:
    metadata = json.load(f)

# Load field data
with h5py.File("neural_field_data.h5", 'r') as f:
    # Get node coordinates
    coords = f['mesh/node_coordinates'][:]

    # Get displacement field
    displacement = f['results/displacement'][:]

    # Get stress field
    stress = f['results/stress/ctetra_stress/data'][:]
    stress_elem_ids = f['results/stress/ctetra_stress/element_ids'][:]

In PyTorch (for neural network training)

import torch
from torch.utils.data import Dataset

class NeuralFieldDataset(Dataset):
    def __init__(self, case_directories):
        self.cases = []
        for case_dir in case_directories:
            h5_file = f"{case_dir}/neural_field_data.h5"
            with h5py.File(h5_file, 'r') as f:
                # Load inputs (mesh, BCs, loads)
                coords = torch.from_numpy(f['mesh/node_coordinates'][:])

                # Load outputs (displacement, stress fields)
                displacement = torch.from_numpy(f['results/displacement'][:])

                self.cases.append({
                    'coords': coords,
                    'displacement': displacement
                })

    def __len__(self):
        return len(self.cases)

    def __getitem__(self, idx):
        return self.cases[idx]

Architecture & Design

Why This Format?

1. Complete Fields, Not Scalars: Neural networks need to learn how stress/displacement varies across the entire structure, not just maximum values.

2. Separation of Concerns: JSON for structure/metadata (human-readable), HDF5 for numerical data (efficient).

3. Future-Proof: Versioned format allows adding new fields without breaking existing data.

4. Physics Preservation: Maintains all physics relationships (mesh topology, BCs, loads → results).

Integration with Atomizer

This parser is Phase 1 of AtomizerField. Future integration:

• Phase 2: Neural network architecture (Graph Neural Networks)
• Phase 3: Training pipeline with physics-informed loss functions
• Phase 4: Integration with main Atomizer dashboard
• Phase 5: Production deployment for real-time optimization

Troubleshooting

Parser Errors

Error	Solution
FileNotFoundError: No model.bdf found	Ensure BDF/DAT file exists in input/ directory
FileNotFoundError: No model.op2 found	Ensure OP2 file exists in output/ directory
pyNastran read error	Check BDF syntax, try opening in text editor
OP2 subcase not found	Ensure analysis ran successfully, check .f06 file

Validation Warnings

Warning	Meaning	Action
No SPCs defined	Model may be unconstrained	Check boundary conditions
No loads defined	Model has no loading	Add forces, pressures, or gravity
Zero displacement	Model not deforming	Check loads and constraints
Very large displacement	Possible rigid body motion	Add constraints or check units

Data Quality Issues

NaN or Inf values:

• Usually indicates analysis convergence failure
• Check .f06 file for error messages
• Verify model is properly constrained

Mismatch in node counts:

• Some nodes may not have results (e.g., rigid elements)
• Check element connectivity
• Validate mesh quality in NX

Example Workflow

Here's a complete example workflow from FEA to neural network training data:

1. Create Parametric Study in NX

# Generate 10 design variants with different thicknesses
# Run each analysis with SOL 101
# Export BDF and OP2 files for each

2. Organize Files

mkdir parametric_study
for i in {1..10}; do
    mkdir -p parametric_study/thickness_${i}/input
    mkdir -p parametric_study/thickness_${i}/output
    # Copy BDF and OP2 files
done

3. Batch Parse

python batch_parser.py parametric_study

4. Review Results

# Check summary
cat parametric_study/batch_processing_summary.json

# Validate a specific case
python validate_parsed_data.py parametric_study/thickness_5

5. Load into Neural Network

from torch.utils.data import DataLoader

dataset = NeuralFieldDataset([
    f"parametric_study/thickness_{i}" for i in range(1, 11)
])

dataloader = DataLoader(dataset, batch_size=4, shuffle=True)

# Ready for training!

Performance

Typical parsing times (on standard laptop):

• Small model (1k elements): ~5 seconds
• Medium model (10k elements): ~15 seconds
• Large model (100k elements): ~60 seconds
• Very large (1M elements): ~10 minutes

File sizes (compressed HDF5):

• Mesh (100k nodes): ~10 MB
• Displacement field (100k nodes × 6 DOF): ~5 MB
• Stress field (100k elements × 10 components): ~8 MB

Requirements

• Python 3.8+
• pyNastran 1.4+
• NumPy 1.20+
• h5py 3.0+
• NX Nastran (any version that outputs .bdf and .op2)

Files in This Repository

File	Purpose
neural_field_parser.py	Main parser - BDF/OP2 to neural field format
validate_parsed_data.py	Data validation and quality checks
batch_parser.py	Batch processing for multiple cases
metadata_template.json	Template for design parameter tracking
requirements.txt	Python dependencies
README.md	This file
Context.md	Project context and vision
Instructions.md	Original implementation instructions

Development

Testing with Example Models

There are example models in the Models/ folder. To test the parser:

# Set up test case
mkdir test_case_001
mkdir test_case_001/input
mkdir test_case_001/output

# Copy example files
cp Models/example_model.bdf test_case_001/input/model.bdf
cp Models/example_model.op2 test_case_001/output/model.op2

# Run parser
python neural_field_parser.py test_case_001

# Validate
python validate_parsed_data.py test_case_001

Extending the Parser

To add new result types (e.g., modal analysis, thermal):

1. Update extract_results() in neural_field_parser.py
2. Add corresponding validation in validate_parsed_data.py
3. Update data structure version if needed
4. Document changes in this README

Contributing

This is part of the AtomizerField project. When making changes:

• Preserve the v1.0 data format for backwards compatibility
• Add comprehensive error handling
• Update validation checks accordingly
• Test with multiple element types
• Document physics assumptions

Future Enhancements

Planned features:

• Support for nonlinear analyses (SOL 106)
• Modal analysis results (SOL 103)
• Thermal analysis (SOL 153)
• Contact results
• Composite material support
• Automatic mesh quality assessment
• Parallel batch processing
• Progress bars for long operations
• Integration with Atomizer dashboard

License

Part of the Atomizer optimization platform.

Support

For issues or questions:

1. Check this README and troubleshooting section
2. Review Context.md for project background
3. Examine example files in Models/ folder
4. Check pyNastran documentation for BDF/OP2 specifics

Version History

v1.0.0 (Current)

• Initial release
• Complete BDF/OP2 parsing
• Support for solid, shell, beam elements
• HDF5 + JSON output format
• Data validation
• Batch processing
• Physics consistency checks

---

AtomizerField: Revolutionizing structural optimization through neural field learning.

Built with Claude Code, designed for the future of engineering.