Atomizer/docs/api/NXOPEN_INTELLISENSE_SETUP.md

# NXOpen Python Intellisense Setup

> **Status**: ✅ Implemented (2025-11-17)
>
> Enable intelligent code completion for NXOpen Python API using Siemens-provided stub files

---

## Overview

Siemens NX 2412 includes Python stub files (`.pyi`) that provide full type hints for the NXOpen API. These enable:

- **Autocomplete**: Suggestions for classes, methods, and properties
- **Type Hints**: Parameter types and return values
- **Documentation**: Inline docstrings and API descriptions
- **Error Detection**: Type checking catches errors before runtime

This dramatically improves development speed and reduces NXOpen API lookup time.

---

## Prerequisites

- **Siemens NX 2412** (or later) installed with Programming Tools
- **VSCode** with **Pylance extension** (usually installed with Python extension)
- **Python 3.11** environment (required for NXOpen module compatibility)

---

## Setup Instructions

### Step 0: Ensure Python 3.11 Environment

NXOpen modules are compiled for Python 3.11. **You must use Python 3.11**:

```bash
# Check your Python version
python --version  # Should show: Python 3.11.x

# If using conda, upgrade atomizer environment:
conda install -n atomizer python=3.11 -y
```

### Step 1: Add NXOpen to Python Path

Create a `.pth` file in your Python environment's site-packages to enable NXOpen imports:

```bash
# For atomizer environment:
# Create file: C:\Users\<username>\anaconda3\envs\atomizer\Lib\site-packages\nxopen.pth
# Contents:
C:\Program Files\Siemens\NX2412\NXBIN\python
```

This allows `import NXOpen` to work in your Python scripts!

### Step 2: Verify Stub Files Exist

Check that stub files are installed:

```bash
# Windows path:
dir "C:\Program Files\Siemens\NX2412\UGOPEN\pythonStubs\NXOpen"

# Should show: __init__.pyi and many module folders (CAE, Assemblies, etc.)
```

**If missing**: Reinstall NX 2412 and ensure "Programming Tools" is checked during installation.

### Step 3: Configure VSCode

Update `.vscode/settings.json` in your Atomizer project:

```json
{
    "python.analysis.typeCheckingMode": "basic",
    "python.analysis.stubPath": "C:\\Program Files\\Siemens\\NX2412\\UGOPEN\\pythonStubs"
}
```

**Note**: Use double backslashes (`\\`) in Windows paths for JSON.

### Step 4: Restart VSCode

Close and reopen VSCode to load the new stub files.

### Step 5: Verify NXOpen Import and Intellisense Works

First, test that NXOpen can be imported:

```python
python
>>> import NXOpen
>>> print("Success! NXOpen is available")
>>> exit()
```

Then test intellisense:

Open `tests/test_nxopen_intellisense.py` and verify:

1. **Import Autocomplete**:
   - Type `import NXOpen.` → Should suggest: Part, Session, CAE, Assemblies, etc.

2. **Method Autocomplete**:
   - Type `session.` → Should suggest: GetSession(), Parts, etc.
   - Type `expressions.` → Should suggest: FindObject, CreateExpression, etc.

3. **Parameter Hints**:
   - Hover over `CreateExpression()` → Shows parameter types and documentation

4. **Documentation Tooltips**:
   - Hover over any NXOpen class/method → Shows docstring

**If working**: ✅ Intellisense is configured correctly!

---

## What You Get

### Before Intellisense:
```python
import NXOpen
session = NXOpen.Session.GetSession()
# ❌ No suggestions when typing "session."
# ❌ No parameter hints for methods
# ❌ Must look up API in documentation
```

### After Intellisense:
```python
import NXOpen
session = NXOpen.Session.GetSession()
# ✅ Type "session." → See: Parts, ListingWindow, LogFile, etc.
# ✅ Type "session.Parts." → See: Work, Display, FindObject, etc.
# ✅ Hover over methods → See parameter types and documentation
# ✅ Catch type errors before running code
```

---

## Available Modules

The stub files cover **all** NXOpen modules:

**Core Modules**:
- `NXOpen.Session` - NX session management
- `NXOpen.Part` - Part objects and operations
- `NXOpen.Assemblies` - Assembly operations

**CAE Modules**:
- `NXOpen.CAE` - Finite element analysis
- `NXOpen.CAE.FemPart` - FEM models
- `NXOpen.CAE.SimSolution` - Solutions and solver control

**Design Modules**:
- `NXOpen.Features` - Parametric features
- `NXOpen.Sketches` - Sketch operations
- `NXOpen.Modeling` - Modeling operations

**And many more**: Drafting, Display, Motion, Optimization, etc.

---

## Example: Using Intellisense During Development

### Scenario: Update Part Expression

**Without Intellisense** (manual lookup required):
```python
# 1. Google: "NXOpen get expression"
# 2. Find documentation
# 3. Copy method signature
# 4. Hope you got it right
work_part.Expressions.FindObject("tip_thickness")
```

**With Intellisense** (guided development):
```python
# 1. Type "work_part.Exp" → Autocomplete suggests "Expressions"
# 2. Type "work_part.Expressions." → See all methods
# 3. Select "FindObject" → See parameter types
# 4. Hover for documentation
work_part.Expressions.FindObject("tip_thickness")  # ✅ Correct!
```

---

## Benefits for Atomizer Development

### 1. **Faster Development**
- No context switching to documentation
- Discover APIs as you type
- Reduce typos and API misuse

### 2. **Better Code Quality**
- Type checking catches errors early
- Method signatures documented inline
- Parameter validation before runtime

### 3. **LLM-Assisted Coding**
When using Claude Code to develop Atomizer:
- Claude can "see" NXOpen API structure via stub files
- Better code generation suggestions
- Reduced hallucination of API methods

### 4. **Onboarding**
- New contributors learn NXOpen API faster
- Inline documentation reduces learning curve
- Explore API without leaving IDE

---

## Integration with Atomizer Workflow

### Journal Script Development

When writing NX journal scripts (`optimization_engine/solve_simulation.py`):

```python
import NXOpen

theSession = NXOpen.Session.GetSession()
workPart = theSession.Parts.Work

# Intellisense shows:
# - workPart.Expressions.FindObject(...)
# - workPart.Expressions.EditWithUnits(...)
# - workPart.Update()
# - workPart.Save(...)
```

### LLM Code Generation

When LLM generates NXOpen code, stub files help:
- Validate generated code against actual API
- Suggest corrections for API misuse
- Provide parameter type hints

### Future: NXOpen Documentation Integration

This is **Step 1** of NXOpen integration. Future work:

1. ✅ **Stub files for intellisense** (current)
2. 🔜 **Documentation scraping** for LLM knowledge base
3. 🔜 **Authenticated docs access** for latest API references
4. 🔜 **LLM-generated journal scripts** with validation

---

## Troubleshooting

### Intellisense Not Working

**Problem**: No autocomplete suggestions appear

**Solutions**:
1. **Check Pylance Extension**: VSCode → Extensions → Search "Pylance" → Ensure installed
2. **Verify Settings**: `.vscode/settings.json` has correct stub path
3. **Check Python Interpreter**: VSCode bottom-left → Select correct Python environment
4. **Restart VSCode**: Close all windows and reopen
5. **Check Stub Path**: Ensure path exists and contains `NXOpen` folder

### Wrong Suggestions

**Problem**: Autocomplete shows incorrect or outdated methods

**Solution**: Ensure stub files match your NX version:
- NX 2412 → Use `NX2412\ugopen\pythonStubs`
- Different NX version → Update stub path in settings

### Type Errors Shown

**Problem**: Pylance shows type errors for valid code

**Solutions**:
1. Set `"python.analysis.typeCheckingMode": "basic"` (not "strict")
2. Add `# type: ignore` for false positives
3. Update stub files if using newer NX version

---

## References

- **Siemens NX Documentation**: [PLM Portal](https://plm.sw.siemens.com)
- **TheScriptingEngineer**: [Blog with NXOpen examples](https://thescriptingengineer.com)
- **Pylance Documentation**: [VSCode Python](https://code.visualstudio.com/docs/python/editing)

---

## Next Steps

Now that intellisense is configured:

1. **Try It**: Open `tests/test_nxopen_intellisense.py` and explore
2. **Develop Faster**: Use autocomplete when writing journal scripts
3. **Contribute**: Help improve Atomizer's NXOpen integration

**See**: [DEVELOPMENT_GUIDANCE.md](../DEVELOPMENT_GUIDANCE.md) for strategic roadmap including NXOpen documentation access.

---

**Implemented By**: Antoine Letarte
**Date**: 2025-11-17
**NX Version**: 2412
**Status**: Production Ready