docs: Add GitHub setup and development guides
This commit is contained in:
262
DEVELOPMENT.md
Normal file
262
DEVELOPMENT.md
Normal file
@@ -0,0 +1,262 @@
|
||||
# Development Guide
|
||||
|
||||
## Project Setup Complete! ✅
|
||||
|
||||
Your NX OptiMaster project has been initialized with the following structure:
|
||||
|
||||
```
|
||||
C:\Users\antoi\Documents\Atomaste\Atomizer\
|
||||
├── .git/ # Git repository
|
||||
├── .gitignore # Ignore patterns
|
||||
├── LICENSE # Proprietary license
|
||||
├── README.md # Main documentation
|
||||
├── GITHUB_SETUP.md # GitHub push instructions
|
||||
├── DEVELOPMENT.md # This file
|
||||
├── pyproject.toml # Python package configuration
|
||||
├── requirements.txt # Pip dependencies
|
||||
│
|
||||
├── config/ # Configuration templates
|
||||
│ ├── nx_config.json.template
|
||||
│ └── optimization_config_template.json
|
||||
│
|
||||
├── mcp_server/ # MCP Server (Phase 1)
|
||||
│ ├── __init__.py
|
||||
│ ├── tools/ # MCP tool implementations
|
||||
│ │ └── __init__.py
|
||||
│ ├── schemas/ # JSON schemas for validation
|
||||
│ └── prompts/ # LLM system prompts
|
||||
│ └── examples/ # Few-shot examples
|
||||
│
|
||||
├── optimization_engine/ # Core optimization (Phase 4)
|
||||
│ ├── __init__.py
|
||||
│ └── result_extractors/ # Pluggable metric extractors
|
||||
│ └── __init__.py # Base classes + registry
|
||||
│
|
||||
├── nx_journals/ # NXOpen scripts (Phase 3)
|
||||
│ ├── __init__.py
|
||||
│ └── utils/ # Helper functions
|
||||
│
|
||||
├── dashboard/ # Web UI (Phase 2)
|
||||
│ ├── frontend/ # React app
|
||||
│ └── backend/ # FastAPI server
|
||||
│
|
||||
├── tests/ # Unit tests
|
||||
├── docs/ # Documentation
|
||||
└── examples/ # Example projects
|
||||
```
|
||||
|
||||
## Current Status: Phase 0 - Foundation ✅
|
||||
|
||||
- [x] Project structure created
|
||||
- [x] Git repository initialized
|
||||
- [x] Python package configuration
|
||||
- [x] License and documentation
|
||||
- [x] Initial commit ready
|
||||
|
||||
## Next Development Phases
|
||||
|
||||
### 🎯 Immediate Next Steps (Choose One)
|
||||
|
||||
#### Option A: Start with MCP Server (Recommended)
|
||||
**Goal**: Get conversational FEA model discovery working
|
||||
|
||||
1. **Implement `discover_fea_model` tool**:
|
||||
```bash
|
||||
# Create the tool
|
||||
touch mcp_server/tools/model_discovery.py
|
||||
```
|
||||
|
||||
- Parse .sim files to extract solutions, expressions, FEM info
|
||||
- Use existing Atomizer patterns from your P04 project
|
||||
- Return structured JSON for LLM consumption
|
||||
|
||||
2. **Set up MCP server skeleton**:
|
||||
```bash
|
||||
# Install MCP SDK
|
||||
pip install mcp
|
||||
|
||||
# Create server entry point
|
||||
touch mcp_server/server.py
|
||||
```
|
||||
|
||||
3. **Test with a real .sim file**:
|
||||
- Point it to one of your existing models
|
||||
- Verify it extracts expressions correctly
|
||||
|
||||
#### Option B: Port Atomizer Optimization Engine
|
||||
**Goal**: Get core optimization working independently
|
||||
|
||||
1. **Copy Atomizer modules**:
|
||||
```bash
|
||||
# From your P04/Atomizer project, copy:
|
||||
cp ../Projects/P04/Atomizer/code/multi_optimizer.py optimization_engine/
|
||||
cp ../Projects/P04/Atomizer/code/config_loader.py optimization_engine/
|
||||
cp ../Projects/P04/Atomizer/code/surrogate_optimizer.py optimization_engine/
|
||||
```
|
||||
|
||||
2. **Adapt for general use**:
|
||||
- Remove Zernike-specific code
|
||||
- Generalize result extraction to use plugin system
|
||||
- Update import paths
|
||||
|
||||
3. **Create a simple test**:
|
||||
```python
|
||||
# tests/test_optimizer.py
|
||||
def test_basic_optimization():
|
||||
config = load_config("config/optimization_config_template.json")
|
||||
optimizer = MultiParameterOptimizer(config)
|
||||
# ...
|
||||
```
|
||||
|
||||
#### Option C: Build Dashboard First
|
||||
**Goal**: Get real-time monitoring UI working
|
||||
|
||||
1. **Set up React frontend**:
|
||||
```bash
|
||||
cd dashboard/frontend
|
||||
npx create-react-app . --template typescript
|
||||
npm install plotly.js recharts
|
||||
```
|
||||
|
||||
2. **Set up FastAPI backend**:
|
||||
```bash
|
||||
cd dashboard/backend
|
||||
touch server.py
|
||||
# Implement WebSocket endpoint for live updates
|
||||
```
|
||||
|
||||
3. **Create mock data endpoint**:
|
||||
- Serve fake optimization history
|
||||
- Test plots and visualizations
|
||||
|
||||
## Recommended Workflow: Iterative Development
|
||||
|
||||
### Week 1: MCP + Model Discovery
|
||||
- Implement `discover_fea_model` tool
|
||||
- Test with real .sim files
|
||||
- Get LLM integration working
|
||||
|
||||
### Week 2: Optimization Engine Port
|
||||
- Copy and adapt Atomizer core modules
|
||||
- Create pluggable result extractors
|
||||
- Test with simple optimization
|
||||
|
||||
### Week 3: NXOpen Bridge
|
||||
- Build file-based communication
|
||||
- Create generic journal dispatcher
|
||||
- Test expression updates
|
||||
|
||||
### Week 4: Dashboard MVP
|
||||
- React frontend skeleton
|
||||
- FastAPI backend with WebSocket
|
||||
- Real-time iteration monitoring
|
||||
|
||||
## Development Commands
|
||||
|
||||
### Python Environment
|
||||
|
||||
```bash
|
||||
# Create conda environment
|
||||
conda create -n nx-optimaster python=3.10
|
||||
conda activate nx-optimaster
|
||||
|
||||
# Install in development mode
|
||||
pip install -e .
|
||||
|
||||
# Install dev dependencies
|
||||
pip install -e ".[dev]"
|
||||
```
|
||||
|
||||
### Testing
|
||||
|
||||
```bash
|
||||
# Run all tests
|
||||
pytest
|
||||
|
||||
# With coverage
|
||||
pytest --cov=mcp_server --cov=optimization_engine
|
||||
|
||||
# Run specific test
|
||||
pytest tests/test_model_discovery.py -v
|
||||
```
|
||||
|
||||
### Code Quality
|
||||
|
||||
```bash
|
||||
# Format code
|
||||
black .
|
||||
|
||||
# Lint
|
||||
ruff check .
|
||||
|
||||
# Type checking
|
||||
mypy mcp_server optimization_engine
|
||||
```
|
||||
|
||||
### Git Workflow
|
||||
|
||||
```bash
|
||||
# Create feature branch
|
||||
git checkout -b feature/model-discovery
|
||||
|
||||
# Make changes, test, commit
|
||||
git add .
|
||||
git commit -m "feat: implement FEA model discovery tool"
|
||||
|
||||
# Push to GitHub
|
||||
git push -u origin feature/model-discovery
|
||||
|
||||
# Merge to main
|
||||
git checkout main
|
||||
git merge feature/model-discovery
|
||||
git push origin main
|
||||
```
|
||||
|
||||
## Integration with Existing Atomizer
|
||||
|
||||
Your existing Atomizer project is at:
|
||||
```
|
||||
C:\Users\antoi\Documents\Atomaste\Projects\P04\Atomizer\
|
||||
```
|
||||
|
||||
You can reference and copy modules from there as needed. Key files to adapt:
|
||||
|
||||
| Atomizer File | New Location | Adaptation Needed |
|
||||
|--------------|--------------|-------------------|
|
||||
| `code/multi_optimizer.py` | `optimization_engine/multi_optimizer.py` | Minimal - works as-is |
|
||||
| `code/config_loader.py` | `optimization_engine/config_loader.py` | Extend schema for extractors |
|
||||
| `code/zernike_Post_Script_NX.py` | `optimization_engine/result_extractors/zernike.py` | Convert to plugin class |
|
||||
| `code/journal_NX_Update_and_Solve.py` | `nx_journals/update_and_solve.py` | Generalize for any .sim |
|
||||
| `code/nx_post_each_iter.py` | `nx_journals/post_process.py` | Use extractor registry |
|
||||
|
||||
## Useful Resources
|
||||
|
||||
- **Optuna Docs**: https://optuna.readthedocs.io/
|
||||
- **NXOpen API**: https://docs.sw.siemens.com/en-US/doc/209349590/
|
||||
- **MCP Protocol**: https://modelcontextprotocol.io/
|
||||
- **FastAPI**: https://fastapi.tiangolo.com/
|
||||
- **React + TypeScript**: https://react-typescript-cheatsheet.netlify.app/
|
||||
|
||||
## Questions to Consider
|
||||
|
||||
Before starting development, decide on:
|
||||
|
||||
1. **Which phase to tackle first?** (MCP, Engine, Dashboard, or NXOpen)
|
||||
2. **Target NX version?** (2306, 2406, or multi-version support)
|
||||
3. **Deployment strategy?** (Local only or client-server architecture)
|
||||
4. **Testing approach?** (Unit tests only or integration tests with real NX)
|
||||
5. **Documentation format?** (Markdown, Sphinx, MkDocs)
|
||||
|
||||
## Getting Help
|
||||
|
||||
When you're ready to start coding:
|
||||
|
||||
1. Choose a phase from the options above
|
||||
2. Tell me which component you want to build first
|
||||
3. I'll create the detailed implementation with working code
|
||||
4. We'll test it with your existing .sim files
|
||||
5. Iterate and expand
|
||||
|
||||
---
|
||||
|
||||
**You're all set!** The foundation is ready. Choose your starting point and let's build! 🚀
|
||||
106
GITHUB_SETUP.md
Normal file
106
GITHUB_SETUP.md
Normal file
@@ -0,0 +1,106 @@
|
||||
# GitHub Setup Guide
|
||||
|
||||
## Creating the Private Repository
|
||||
|
||||
1. **Go to GitHub**: https://github.com/new
|
||||
|
||||
2. **Repository Settings**:
|
||||
- **Owner**: Your GitHub username or organization (e.g., `atomaste`)
|
||||
- **Repository name**: `nx-optimaster` (or your preferred name)
|
||||
- **Description**: "Advanced optimization platform for Siemens NX Simcenter with LLM integration"
|
||||
- **Visibility**: ✅ **Private**
|
||||
- **DO NOT** initialize with README, .gitignore, or license (we already have these)
|
||||
|
||||
3. **Click "Create repository"**
|
||||
|
||||
## Pushing to GitHub
|
||||
|
||||
After creating the repository on GitHub, run these commands:
|
||||
|
||||
```bash
|
||||
cd /c/Users/antoi/Documents/Atomaste/Atomizer
|
||||
|
||||
# Add the remote repository
|
||||
git remote add origin https://github.com/YOUR-USERNAME/nx-optimaster.git
|
||||
|
||||
# OR if using SSH:
|
||||
# git remote add origin git@github.com:YOUR-USERNAME/nx-optimaster.git
|
||||
|
||||
# Push the initial commit
|
||||
git branch -M main
|
||||
git push -u origin main
|
||||
```
|
||||
|
||||
## Verify Push
|
||||
|
||||
Visit your repository at: `https://github.com/YOUR-USERNAME/nx-optimaster`
|
||||
|
||||
You should see:
|
||||
- README.md displayed on the main page
|
||||
- All 12 files committed
|
||||
- Private repository badge
|
||||
|
||||
## Next Steps
|
||||
|
||||
### Set Up GitHub Actions (Optional)
|
||||
|
||||
Create `.github/workflows/tests.yml` for automated testing:
|
||||
|
||||
```yaml
|
||||
name: Tests
|
||||
|
||||
on: [push, pull_request]
|
||||
|
||||
jobs:
|
||||
test:
|
||||
runs-on: windows-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- uses: actions/setup-python@v4
|
||||
with:
|
||||
python-version: '3.10'
|
||||
- run: pip install -r requirements.txt
|
||||
- run: pytest
|
||||
```
|
||||
|
||||
### Protect Main Branch
|
||||
|
||||
Settings → Branches → Add rule:
|
||||
- Branch name pattern: `main`
|
||||
- ✅ Require pull request reviews before merging
|
||||
- ✅ Require status checks to pass
|
||||
|
||||
### Add Collaborators
|
||||
|
||||
Settings → Collaborators → Add people
|
||||
|
||||
## Clone on Another Machine
|
||||
|
||||
```bash
|
||||
git clone https://github.com/YOUR-USERNAME/nx-optimaster.git
|
||||
cd nx-optimaster
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
## Useful Git Commands
|
||||
|
||||
```bash
|
||||
# Check status
|
||||
git status
|
||||
|
||||
# View commit history
|
||||
git log --oneline
|
||||
|
||||
# Create a new branch
|
||||
git checkout -b feature/new-feature
|
||||
|
||||
# Push branch to GitHub
|
||||
git push -u origin feature/new-feature
|
||||
|
||||
# Pull latest changes
|
||||
git pull origin main
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Note**: Replace `YOUR-USERNAME` with your actual GitHub username throughout this guide.
|
||||
Reference in New Issue
Block a user