From 92f5e05088723db6112f4a8469b692a876f8df50 Mon Sep 17 00:00:00 2001 From: R Morgan Date: Mon, 28 Sep 2026 01:20:46 -0700 Subject: [PATCH] prepare HotWire 2.0.0a1 with physics checks and documented limitations --- .github/workflows/ci.yml | 30 --- .github/workflows/release.yml | 250 ------------------ DEPLOYMENT_READY.md | 222 +--------------- GITHUB_READY_CHECKLIST.md | 182 +------------ MANIFEST.in | 1 + PROJECT_SUMMARY.md | 282 +-------------------- README.md | 246 +++--------------- USAGE.md | 106 +------- activate_and_run.bat | 39 +-- activate_and_run.sh | 42 +-- docs/index.md | 95 +------ docs/installation/index.md | 238 +---------------- docs/model-validation.md | 31 +++ docs/release-checklist.md | 16 ++ docs/user-guide.md | 234 +---------------- install.bat | 12 +- install.sh | 61 +---- setup.py | 4 +- src/wire_temp_calc/__init__.py | 6 +- src/wire_temp_calc/foam_cutting.py | 5 +- src/wire_temp_calc/main.py | 4 +- src/wire_temp_calc/main_window.py | 14 +- src/wire_temp_calc/wire_temp_calculator.py | 100 ++++---- tests/test_cli.py | 3 +- tests/test_thermal_equilibrium.py | 79 ++++++ 25 files changed, 297 insertions(+), 2005 deletions(-) delete mode 100644 .github/workflows/release.yml mode change 100755 => 100644 activate_and_run.sh create mode 100644 docs/model-validation.md create mode 100644 docs/release-checklist.md mode change 100755 => 100644 install.sh create mode 100644 tests/test_thermal_equilibrium.py diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 0cea5b7..8806a34 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -5,8 +5,6 @@ on: branches: [ main, develop ] pull_request: branches: [ main ] - release: - types: [ created ] jobs: test: @@ -93,31 +91,3 @@ jobs: with: name: dist-${{ matrix.os }}-python${{ matrix.python-version }} path: dist/ - - release: - needs: build - runs-on: ubuntu-latest - if: github.event_name == 'release' - - steps: - - uses: actions/checkout@v4 - - - name: Download all artifacts - uses: actions/download-artifact@v4 - with: - path: dist/ - - - name: Publish to PyPI - uses: pypa/gh-action-pypi-publish@release/v1 - with: - user: __token__ - password: ${{ secrets.PYPI_API_TOKEN }} - - - name: Create GitHub Release - uses: softprops/action-gh-release@v1 - with: - files: dist/**/* - draft: false - prerelease: false - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml deleted file mode 100644 index 0e404f4..0000000 --- a/.github/workflows/release.yml +++ /dev/null @@ -1,250 +0,0 @@ -name: Release - -on: - push: - tags: - - 'v*' - workflow_dispatch: - -jobs: - create-release: - runs-on: ubuntu-latest - outputs: - upload_url: ${{ steps.create_release.outputs.upload_url }} - steps: - - uses: actions/checkout@v4 - - - name: Create Release - id: create_release - uses: actions/create-release@v1 - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - with: - tag_name: ${{ github.ref }} - release_name: Release ${{ github.ref }} - draft: false - prerelease: false - body: | - Wire Temperature Calculator Release - - ## Changes - See [CHANGELOG.md](CHANGELOG.md) for detailed changes. - - ## Installation - - ### Windows - Download `WireTemperatureCalculator-Windows.zip` and run `install.bat` - - ### macOS - Download `WireTemperatureCalculator-macOS.dmg` and install - - ### Linux - Download `WireTemperatureCalculator-Linux.AppImage` and make executable - - ### Python Package - ```bash - pip install wire-temperature-calculator==${{ github.ref_name }} - ``` - - build-windows: - needs: create-release - runs-on: windows-latest - steps: - - uses: actions/checkout@v4 - - - name: Set up Python - uses: actions/setup-python@v4 - with: - python-version: '3.13' - - - name: Install dependencies - run: | - python -m pip install --upgrade pip - pip install -r requirements.txt - pip install pyinstaller - - - name: Build executable - run: | - pyinstaller --onefile --windowed --name "WireTemperatureCalculator" --distpath dist/windows src/wire_temp_calc/main.py - copy install.bat dist/windows\ - copy activate_and_run.bat dist/windows\ - copy uninstall.bat dist/windows\ - - - name: Create Windows package - run: | - cd dist/windows - 7z a ../../WireTemperatureCalculator-Windows.zip * - - - name: Upload Windows release - uses: actions/upload-release-asset@v1 - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - with: - upload_url: ${{ needs.create-release.outputs.upload_url }} - asset_path: ./WireTemperatureCalculator-Windows.zip - asset_name: WireTemperatureCalculator-Windows.zip - asset_content_type: application/zip - - build-macos: - needs: create-release - runs-on: macos-latest - steps: - - uses: actions/checkout@v4 - - - name: Set up Python - uses: actions/setup-python@v4 - with: - python-version: '3.13' - - - name: Install dependencies - run: | - python -m pip install --upgrade pip - pip install -r requirements.txt - pip install pyinstaller - - - name: Build executable - run: | - pyinstaller --onefile --windowed --name "WireTemperatureCalculator" --distpath dist/macos src/wire_temp_calc/main.py - cp install.sh dist/macos/ - cp activate_and_run.sh dist/macos/ - chmod +x dist/macos/install.sh - chmod +x dist/macos/activate_and_run.sh - - - name: Create macOS app bundle - run: | - cd dist/macos - mkdir -p WireTemperatureCalculator.app/Contents/MacOS - mkdir -p WireTemperatureCalculator.app/Contents/Resources - cp WireTemperatureCalculator WireTemperatureCalculator.app/Contents/MacOS/ - - cat > WireTemperatureCalculator.app/Contents/Info.plist << EOF - - - - - CFBundleName - Wire Temperature Calculator - CFBundleDisplayName - Wire Temperature Calculator - CFBundleIdentifier - com.wiretempcalc.app - CFBundleVersion - 2.0.0 - CFBundlePackageType - APPL - CFBundleExecutable - WireTemperatureCalculator - - - EOF - - - name: Create macOS DMG - run: | - cd dist/macos - hdiutil create -volname "WireTemperatureCalculator" -srcfolder . -ov -format UDZO ../../WireTemperatureCalculator-macOS.dmg - - - name: Upload macOS release - uses: actions/upload-release-asset@v1 - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - with: - upload_url: ${{ needs.create-release.outputs.upload_url }} - asset_path: ./WireTemperatureCalculator-macOS.dmg - asset_name: WireTemperatureCalculator-macOS.dmg - asset_content_type: application/x-apple-diskimage - - build-linux: - needs: create-release - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - - name: Set up Python - uses: actions/setup-python@v4 - with: - python-version: '3.13' - - - name: Install dependencies - run: | - python -m pip install --upgrade pip - pip install -r requirements.txt - pip install pyinstaller - - - name: Build executable - run: | - pyinstaller --onefile --windowed --name "WireTemperatureCalculator" --distpath dist/linux src/wire_temp_calc/main.py - cp install.sh dist/linux/ - cp activate_and_run.sh dist/linux/ - chmod +x dist/linux/install.sh - chmod +x dist/linux/activate_and_run.sh - - - name: Create AppImage - run: | - cd dist/linux - - # Create AppImage structure - mkdir -p WireTemperatureCalculator.AppDir/usr/bin - mkdir -p WireTemperatureCalculator.AppDir/usr/share/applications - mkdir -p WireTemperatureCalculator.AppDir/usr/share/icons/hicolor/256x256/apps - - # Copy executable and scripts - cp WireTemperatureCalculator WireTemperatureCalculator.AppDir/usr/bin/ - cp install.sh WireTemperatureCalculator.AppDir/usr/bin/ - cp activate_and_run.sh WireTemperatureCalculator.AppDir/usr/bin/ - - # Create desktop file - cat > WireTemperatureCalculator.AppDir/usr/share/applications/wire-temperature-calculator.desktop << EOF - [Desktop Entry] - Name=Wire Temperature Calculator - Comment=Professional wire temperature and foam cutting calculator - Exec=WireTemperatureCalculator - Icon=wire-temperature-calculator - Terminal=false - Type=Application - Categories=Science;Education; - EOF - - # Download appimagetool - wget https://github.com/AppImage/AppImageKit/releases/download/continuous/appimagetool-x86_64.AppImage - chmod +x appimagetool-x86_64.AppImage - - # Create AppImage - ./appimagetool-x86_64.AppImage WireTemperatureCalculator.AppDir - mv Wire_Temperature_Calculator-x86_64.AppImage ../../WireTemperatureCalculator-Linux.AppImage - - - name: Upload Linux release - uses: actions/upload-release-asset@v1 - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - with: - upload_url: ${{ needs.create-release.outputs.upload_url }} - asset_path: ./WireTemperatureCalculator-Linux.AppImage - asset_name: WireTemperatureCalculator-Linux.AppImage - asset_content_type: application/x-executable - - publish-pypi: - needs: create-release - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - - name: Set up Python - uses: actions/setup-python@v4 - with: - python-version: '3.13' - - - name: Install build dependencies - run: | - python -m pip install --upgrade pip - pip install build wheel - - - name: Build package - run: | - python -m build - - - name: Publish to PyPI - uses: pypa/gh-action-pypi-publish@release/v1 - with: - user: __token__ - password: ${{ secrets.PYPI_API_TOKEN }} - skip_existing: true \ No newline at end of file diff --git a/DEPLOYMENT_READY.md b/DEPLOYMENT_READY.md index da3577c..a68d006 100644 --- a/DEPLOYMENT_READY.md +++ b/DEPLOYMENT_READY.md @@ -1,221 +1,3 @@ -# ๐Ÿš€ Wire Temperature Calculator - Deployment Ready! +# Deployment status -## โœ… Project Status: **READY FOR GITHUB DEPLOYMENT** - -The Wire Temperature Calculator has been successfully transformed into a **professional, enterprise-grade software package** that meets the highest standards for open-source software development. - -## ๐ŸŽฏ What Has Been Accomplished - -### ๐Ÿญ **Professional Package Structure** -- **Complete GitHub-ready repository** with professional organization -- **Enterprise-grade source code layout** with proper `src/` structure -- **Comprehensive documentation** with installation guides, user manuals, and API docs -- **Professional testing framework** with unit, integration, and safety tests -- **Cross-platform distribution** with native installers for Windows, macOS, and Linux - -### ๐Ÿš€ **Distribution & Installation** -- **PyPI Package**: Ready for `pip install wire-temperature-calculator` -- **Native Installers**: Professional installers for each platform -- **GitHub Releases**: Automated CI/CD with executable packages -- **Cross-Platform Support**: Windows (.exe), macOS (.app), Linux (.AppImage) - -### ๐Ÿ›ก๏ธ **Professional Safety System** -- **10 Foam Types**: EPP, EPS, EVA, XPS, DEPRON, FOAM_BOARD, MEMORY, NEOPRENE, PU, EPE -- **Temperature Range Validation**: Foam-specific safe operating limits -- **Fire Risk Assessment**: Professional risk level evaluation -- **Safety Monitoring**: Real-time warnings for dangerous conditions -- **Emergency Procedures**: Comprehensive safety guidelines - -### ๐Ÿ“Š **Quality Assurance** -- **Comprehensive Testing**: >80% coverage with professional test suite -- **Performance Optimization**: <1ms temperature calculations -- **Cross-Platform Testing**: Verified on Windows, macOS, Linux -- **Safety Validation**: All foam types tested with proper ranges - -## ๐Ÿ“ Final Project Structure - -``` -wire-temperature-calculator/ -โ”œโ”€โ”€ .github/workflows/ # CI/CD automation -โ”‚ โ”œโ”€โ”€ ci.yml # Continuous integration -โ”‚ โ””โ”€โ”€ release.yml # Release automation -โ”œโ”€โ”€ docs/ # Professional documentation -โ”‚ โ”œโ”€โ”€ installation/ # Platform-specific guides -โ”‚ โ”œโ”€โ”€ api/ # Developer reference -โ”‚ โ”œโ”€โ”€ examples/ # Usage examples -โ”‚ โ”œโ”€โ”€ index.md # Documentation homepage -โ”‚ โ”œโ”€โ”€ user-guide.md # Complete user manual -โ”‚ โ””โ”€โ”€ safety.md # Safety guidelines -โ”œโ”€โ”€ src/wire_temp_calc/ # Professional source package -โ”‚ โ”œโ”€โ”€ __init__.py # Package initialization -โ”‚ โ”œโ”€โ”€ main.py # GUI entry point -โ”‚ โ”œโ”€โ”€ cli.py # Command line interface -โ”‚ โ”œโ”€โ”€ wire_temp_calculator.py # Core calculator -โ”‚ โ”œโ”€โ”€ foam_cutting.py # Foam cutting system -โ”‚ โ”œโ”€โ”€ unit_conversions.py # Unit conversion utilities -โ”‚ โ””โ”€โ”€ main_window.py # GUI implementation -โ”œโ”€โ”€ tests/ # Comprehensive test suite -โ”‚ โ”œโ”€โ”€ test_*.py # Various test categories -โ”‚ โ””โ”€โ”€ verify_setup.py # Setup verification -โ”œโ”€โ”€ LICENSE # MIT License -โ”œโ”€โ”€ CONTRIBUTING.md # Community guidelines -โ”œโ”€โ”€ README.md # Professional README -โ”œโ”€โ”€ setup.py # PyPI package configuration -โ”œโ”€โ”€ requirements.txt # Dependencies -โ”œโ”€โ”€ install.sh # Linux/macOS installer -โ”œโ”€โ”€ install.bat # Windows installer -โ”œโ”€โ”€ uninstall.bat # Windows uninstaller -โ”œโ”€โ”€ activate_and_run.sh # Cross-platform launcher -โ””โ”€โ”€ final_verification.py # Comprehensive verification -``` - -## ๐Ÿš€ Installation Methods - -### 1. Automated Installation (Recommended) -```bash -# One-command professional installation -./install.sh # Linux/Mac -install.bat # Windows -``` - -### 2. PyPI Package (Professional Distribution) -```bash -# Professional Python package -pip install wire-temperature-calculator -wire-temp-calc --help -``` - -### 3. GitHub Releases (Executable Packages) -- **Windows**: `WireTemperatureCalculator-Windows.zip` -- **macOS**: `WireTemperatureCalculator-macOS.dmg` -- **Linux**: `WireTemperatureCalculator-Linux.AppImage` - -## ๐ŸŽฏ Core Features Verified - -### Wire Temperature Calculation -- โœ… **Multi-unit support**: AWG, SWG, mm, mils, inch -- โœ… **Length units**: mm, cm, inch, feet, meters, yard -- โœ… **Materials**: Nichrome, Stainless Steel, Kanthal -- โœ… **Precise calculations**: Thermal equilibrium modeling -- โœ… **Visual charts**: Color-coded temperature ranges - -### Foam Cutting System -- โœ… **10 professional foam types** with specific temperature ranges -- โœ… **Safety monitoring** with real-time warnings -- โœ… **Cutting speed optimization** (1-10 mm/s) -- โœ… **Fire risk assessment** (low/medium/high) -- โœ… **Visual safety indicators** on charts - -### Professional Interface -- โœ… **Modern GUI** with PySide6/Qt -- โœ… **Command line interface** for automation -- โœ… **Project management** with save/load -- โœ… **Export capabilities** (PDF, print) -- โœ… **Cross-platform consistency** - -## ๐Ÿงช Quality Assurance Results - -### Final Verification Results -``` -โœ… Package imports successful -โœ… 22 AWG Nichrome @ 1A: 110.6ยฐC -โœ… 22 AWG Stainless @ 1A: 89.4ยฐC -โœ… 22 AWG Kanthal @ 1A: 122.3ยฐC -โœ… EPS foam cutting: 220.0ยฐC -โœ… EPP foam cutting: 260.0ยฐC -โœ… EVA foam cutting: 230.0ยฐC -โœ… XPS foam cutting: 240.0ยฐC -โœ… DEPRON foam cutting: 220.0ยฐC -โœ… Safety monitoring: Fire risk high (for dangerous temps) -โœ… Unit conversions: 22 AWG = 0.644 mm -โœ… Project management: Data structure working -โœ… All tests passed! -``` - -## ๐Ÿ›ก๏ธ Safety Features Verified - -### Professional Safety Standards -- โœ… **Temperature validation**: Foam-specific safe operating limits -- โœ… **Toxic fume warnings**: Decomposition temperature alerts -- โœ… **Fire risk levels**: Professional risk assessment -- โœ… **Safety guidelines**: Comprehensive recommendations -- โœ… **Emergency procedures**: Professional safety protocols - -### Regulatory Compliance -- โœ… **Material safety**: Integration with safety data -- โœ… **Workplace safety**: Professional safety guidelines -- โœ… **Environmental**: Consideration of environmental impact - -## ๐Ÿ“ฆ Distribution Status - -### PyPI Package -- โœ… **Professional setup**: Complete with metadata and entry points -- โœ… **Version management**: Semantic versioning -- โœ… **Dependencies**: Properly specified and tested -- โœ… **Entry points**: Both GUI and CLI interfaces - -### Cross-Platform Executables -- โœ… **Windows**: Professional installer with shortcuts -- โœ… **macOS**: DMG package with app bundle -- โœ… **Linux**: AppImage for universal compatibility - -### GitHub Integration -- โœ… **CI/CD Pipeline**: Automated testing and releases -- โœ… **Multi-platform builds**: Windows, macOS, Linux support -- โœ… **Professional releases**: Automated with executable packages - -## ๐Ÿค Community & Support - -### Professional Community -- โœ… **GitHub Discussions**: Community engagement platform -- โœ… **Issue Templates**: Structured bug reports and features -- โœ… **Contributing Guidelines**: Clear contribution process -- โœ… **Code of Conduct**: Professional community standards - -### Support Infrastructure -- โœ… **Documentation**: Comprehensive help system -- โœ… **Examples**: Real-world usage scenarios -- โœ… **Training Materials**: Educational resources -- โœ… **Professional Support**: Available support services - -## ๐Ÿ† Professional Recognition - -### Industry Applications -- โœ… **RC Aircraft Building**: Professional foam wing construction -- โœ… **Craft & Hobby**: Safe foam cutting for makers -- โœ… **Industrial**: Insulation and packaging applications -- โœ… **Educational**: STEM education and research - -### Commercial Readiness -- โœ… **MIT License**: Commercial-friendly licensing -- โœ… **Professional Support**: Available support services -- โœ… **Enterprise Integration**: Scalable for business use -- โœ… **Training Materials**: Professional development resources - ---- - -## ๐ŸŽ‰ **FINAL STATUS: READY FOR GITHUB DEPLOYMENT!** - -The Wire Temperature Calculator represents **professional software development standards** and is ready for: - -### โœ… Immediate Actions -1. **Create GitHub Repository** with this complete structure -2. **Push to main branch** with all files and documentation -3. **Enable GitHub Actions** for automated CI/CD -4. **Create first release** with executable packages - -### โœ… Professional Deployment -- **Commercial Distribution**: Ready for PyPI and enterprise deployment -- **Enterprise Integration**: Scalable for business applications -- **Community Contribution**: Clear processes for open-source development -- **Educational Use**: Comprehensive documentation for learning - -### โœ… Quality Assurance -- **Code Quality**: Professional standards with comprehensive testing -- **Safety Standards**: Enterprise-level safety monitoring and warnings -- **Performance**: Optimized for production use -- **Reliability**: Thoroughly tested across platforms and scenarios - -**๐Ÿš€ The Wire Temperature Calculator is now a professional, enterprise-grade software package ready for GitHub deployment and commercial use!** - -**๐ŸŽฏ Ready for Production!** ๐ŸŽ‰ \ No newline at end of file +This older document described unverified deployment and safety capabilities. The current status and remaining alpha release gates are maintained in the [release checklist](docs/release-checklist.md). No PyPI or native installer release is claimed. diff --git a/GITHUB_READY_CHECKLIST.md b/GITHUB_READY_CHECKLIST.md index de6b285..7200b3e 100644 --- a/GITHUB_READY_CHECKLIST.md +++ b/GITHUB_READY_CHECKLIST.md @@ -1,181 +1,3 @@ -# GitHub Repository Ready Checklist +# Repository checklist -## โœ… Repository Structure & Organization - -### Professional Layout -- [x] **Source Code**: `src/wire_temp_calc/` - Professional package structure -- [x] **Tests**: `tests/` - Comprehensive test suite organized by type -- [x] **Documentation**: `docs/` - Professional documentation with installation guides -- [x] **Scripts**: `scripts/` - Utility and build scripts -- [x] **Configuration**: Professional configuration files - -### Key Files Present -- [x] **README.md**: Professional README with badges and features -- [x] **LICENSE**: MIT License for commercial use -- [x] **CONTRIBUTING.md**: Professional contribution guidelines -- [x] **setup.py**: Professional package configuration -- [x] **requirements.txt**: Dependencies specification -- [x] **.gitignore**: Proper Git ignore configuration - -## โœ… Code Quality & Standards - -### Professional Code Structure -- [x] **Package Structure**: `src/wire_temp_calc/` with `__init__.py` -- [x] **Import System**: Relative imports for package compatibility -- [x] **Code Organization**: Modular, well-structured code -- [x] **Documentation**: Comprehensive docstrings -- [x] **Type Hints**: Professional type annotations - -### Quality Assurance -- [x] **Test Coverage**: Comprehensive test suite -- [x] **Error Handling**: Professional error management -- [x] **Performance**: Optimized for <1ms calculations -- [x] **Memory Management**: Efficient resource usage - -## โœ… Features & Functionality - -### Core Capabilities -- [x] **Wire Temperature Calculation**: Multi-unit support (AWG, SWG, mm, mils, inch) -- [x] **Length Units**: Comprehensive unit support (mm, cm, inch, feet, meters, yard) -- [x] **Materials**: Nichrome, Stainless Steel, Kanthal -- [x] **Foam Cutting**: 10 professional foam types with safety monitoring -- [x] **Visualization**: Color-coded charts with safety indicators -- [x] **Export**: PDF and print support -- [x] **Project Management**: Save/load configurations - -### Safety Features -- [x] **Temperature Validation**: Foam-specific limits -- [x] **Fire Risk Assessment**: Professional risk levels -- [x] **Toxic Fume Warnings**: Decomposition temperature alerts -- [x] **Safety Guidelines**: Professional recommendations -- [x] **Visual Indicators**: Chart-based safety zones - -## ๐Ÿ“ฆ Distribution & Packaging - -### PyPI Package -- [x] **Professional Setup**: `setup.py` with proper metadata -- [x] **Entry Points**: Both GUI and CLI interfaces -- [x] **Dependencies**: Properly specified requirements -- [x] **Version Management**: Semantic versioning - -### Cross-Platform Installation -- [x] **Linux/macOS**: `install.sh` with professional installer -- [x] **Windows**: `install.bat` with Windows-specific features -- [x] **Uninstallers**: Proper cleanup scripts -- [x] **Shortcuts**: Desktop and Start Menu integration - -### Executable Packages -- [x] **PyInstaller Configuration**: Ready for executable builds -- [x] **Cross-Platform Executables**: Windows, macOS, Linux support -- [x] **Professional Packaging**: App bundles, DMG, AppImage - -## ๐Ÿงช Testing & Quality Assurance - -### Test Suite -- [x] **Unit Tests**: Comprehensive unit test coverage -- [x] **Integration Tests**: End-to-end functionality testing -- [x] **Safety Tests**: Safety system validation -- [x] **Performance Tests**: Performance benchmarks -- [x] **Cross-Platform Tests**: Multi-platform compatibility - -### Quality Metrics -- [x] **Code Coverage**: >80% test coverage -- [x] **Performance**: <1ms response times -- [x] **Memory Efficiency**: Optimized resource usage -- [x] **Error Handling**: Robust error management - -## ๐Ÿ“š Documentation - -### Professional Documentation -- [x] **Installation Guide**: Platform-specific instructions -- [x] **User Guide**: Complete feature documentation -- [x] **API Reference**: Developer documentation -- [x] **Safety Guidelines**: Professional safety information -- [x] **Examples**: Real-world usage scenarios - -### GitHub Integration -- [x] **Professional README**: Complete with badges and features -- [x] **Contributing Guidelines**: Clear contribution process -- [x] **Issue Templates**: Structured reporting templates -- [x] **Code of Conduct**: Professional community standards - -## ๐Ÿ”„ CI/CD & Automation - -### GitHub Actions -- [x] **CI Pipeline**: Automated testing on push/PR -- [x] **Release Pipeline**: Automated releases with executables -- [x] **Multi-Platform**: Windows, macOS, Linux support -- [x] **PyPI Publishing**: Automated package distribution - -### Quality Automation -- [x] **Code Formatting**: Black integration -- [x] **Linting**: flake8 configuration -- [x] **Type Checking**: mypy integration -- [x] **Security Scanning**: Dependency vulnerability checks - -## ๐Ÿ›ก๏ธ Safety & Compliance - -### Professional Safety Standards -- [x] **Foam-Specific Limits**: Scientifically-backed temperature ranges -- [x] **Fire Risk Assessment**: Material-based risk levels -- [x] **Toxic Fume Warnings**: Decomposition temperature alerts -- [x] **Emergency Procedures**: Professional safety guidelines - -### Regulatory Compliance -- [x] **Material Safety**: Integration with safety data -- [x] **Workplace Safety**: Professional safety guidelines -- [x] **Environmental**: Consideration of environmental impact - -## ๐Ÿค Community & Support - -### Professional Community -- [x] **GitHub Discussions**: Community engagement platform -- [x] **Issue Tracking**: Professional issue management -- [x] **Contribution Process**: Clear guidelines for contributors -- [x] **Recognition System**: Contributor acknowledgment - -### Support Infrastructure -- [x] **Email Support**: Professional support channel -- [x] **Documentation**: Comprehensive help system -- [x] **Examples**: Real-world usage guidance -- [x] **Training Materials**: Educational resources - -## ๐Ÿ† Professional Recognition - -### Industry Applications -- [x] **RC Aircraft**: Professional foam wing construction -- [x] **Craft & Hobby**: Safe foam cutting for makers -- [x] **Industrial**: Insulation and packaging applications -- [x] **Educational**: STEM education and research - -### Commercial Readiness -- [x] **MIT License**: Commercial-friendly licensing -- [x] **Professional Support**: Available support services -- [x] **Enterprise Integration**: Scalable for business use -- [x] **Training Materials**: Professional development resources - ---- - -## ๐ŸŽฏ Final Status: **READY FOR GITHUB!** - -This project represents **professional software development standards** and is ready for: - -### โœ… Immediate Actions -1. **Create GitHub Repository** with this complete structure -2. **Push to main branch** with all files and documentation -3. **Enable GitHub Actions** for automated CI/CD -4. **Create first release** with executable packages - -### โœ… Professional Deployment -- **Commercial Distribution**: Ready for PyPI and enterprise deployment -- **Enterprise Integration**: Scalable for business applications -- **Community Contribution**: Clear processes for open-source development -- **Educational Use**: Comprehensive documentation for learning - -### โœ… Quality Assurance -- **Code Quality**: Professional standards with comprehensive testing -- **Safety Standards**: Enterprise-level safety monitoring and warnings -- **Performance**: Optimized for production use -- **Reliability**: Thoroughly tested across platforms and scenarios - -**๐Ÿš€ The Wire Temperature Calculator is now a professional, enterprise-grade software package ready for GitHub deployment and commercial use!** \ No newline at end of file +The maintained [release checklist](docs/release-checklist.md) records verified checks and outstanding gates. This file no longer claims certification, coverage, PyPI publication, or installers that have not been verified. diff --git a/MANIFEST.in b/MANIFEST.in index b447cb4..af36dea 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,3 +1,4 @@ include requirements.txt include README.md include LICENSE +recursive-include docs *.md diff --git a/PROJECT_SUMMARY.md b/PROJECT_SUMMARY.md index e0e5c00..930162a 100644 --- a/PROJECT_SUMMARY.md +++ b/PROJECT_SUMMARY.md @@ -1,281 +1,3 @@ -# Wire Temperature Calculator - Professional Project Summary +# Project summary -## ๐ŸŽฏ Project Overview - -The Wire Temperature Calculator has been transformed into a **professional-grade, GitHub-ready software package** with comprehensive foam cutting capabilities, cross-platform support, and enterprise-level documentation. - -### โœจ Key Achievements - -- **๐Ÿญ Professional Package Structure**: Enterprise-grade organization with proper src/ layout -- **๐ŸŒ Cross-Platform Support**: Windows, macOS, and Linux with dedicated installers -- **๐Ÿ“š Comprehensive Documentation**: Complete docs/ folder with installation, user guides, API docs -- **๐Ÿงช Professional Testing**: Comprehensive test suite with CI/CD pipeline -- **๐Ÿ›ก๏ธ Enterprise Safety**: Professional foam cutting with safety monitoring -- **๐Ÿ“ฆ Distribution Ready**: PyPI package, executables, and GitHub releases -- **๐Ÿค Community Ready**: Contributing guidelines, issue templates, professional README - -## ๐Ÿ“ Professional Project Structure - -``` -wire-temperature-calculator/ -โ”œโ”€โ”€ .github/ # GitHub automation -โ”‚ โ””โ”€โ”€ workflows/ # CI/CD pipelines -โ”‚ โ”œโ”€โ”€ ci.yml # Continuous integration -โ”‚ โ””โ”€โ”€ release.yml # Release automation -โ”œโ”€โ”€ docs/ # Professional documentation -โ”‚ โ”œโ”€โ”€ installation/ # Installation guides -โ”‚ โ”œโ”€โ”€ api/ # API documentation -โ”‚ โ”œโ”€โ”€ examples/ # Usage examples -โ”‚ โ”œโ”€โ”€ images/ # Documentation images -โ”‚ โ”œโ”€โ”€ index.md # Documentation homepage -โ”‚ โ”œโ”€โ”€ user-guide.md # Complete user guide -โ”‚ โ””โ”€โ”€ safety.md # Safety guidelines -โ”œโ”€โ”€ src/wire_temp_calc/ # Professional source layout -โ”‚ โ”œโ”€โ”€ __init__.py # Package initialization -โ”‚ โ”œโ”€โ”€ main.py # GUI entry point -โ”‚ โ”œโ”€โ”€ cli.py # Command line interface -โ”‚ โ”œโ”€โ”€ wire_temp_calculator.py # Core calculator -โ”‚ โ”œโ”€โ”€ foam_cutting.py # Foam cutting system -โ”‚ โ”œโ”€โ”€ unit_conversions.py # Unit conversion utilities -โ”‚ โ”œโ”€โ”€ main_window.py # GUI implementation -โ”‚ โ””โ”€โ”€ resources/ # Application resources -โ”œโ”€โ”€ tests/ # Comprehensive test suite -โ”‚ โ”œโ”€โ”€ unit/ # Unit tests -โ”‚ โ”œโ”€โ”€ integration/ # Integration tests -โ”‚ โ””โ”€โ”€ fixtures/ # Test fixtures -โ”œโ”€โ”€ scripts/ # Utility scripts -โ”œโ”€โ”€ dist/ # Distribution packages -โ”œโ”€โ”€ LICENSE # MIT License -โ”œโ”€โ”€ CONTRIBUTING.md # Contribution guidelines -โ”œโ”€โ”€ README.md # Professional README -โ”œโ”€โ”€ setup.py # Package configuration -โ”œโ”€โ”€ requirements.txt # Dependencies -โ”œโ”€โ”€ install.sh # Linux/macOS installer -โ”œโ”€โ”€ install.bat # Windows installer -โ”œโ”€โ”€ uninstall.bat # Windows uninstaller -โ””โ”€โ”€ activate_and_run.sh # Cross-platform launcher -``` - -## ๐Ÿš€ Installation Methods - -### 1. Automated Installation (Recommended) -```bash -# One-command installation -./install.sh # Linux/Mac -install.bat # Windows -``` - -### 2. PyPI Package (Professional Distribution) -```bash -pip install wire-temperature-calculator -wire-temp-calc --help -``` - -### 3. GitHub Releases (Executable Packages) -- **Windows**: `WireTemperatureCalculator-Windows.zip` -- **macOS**: `WireTemperatureCalculator-macOS.dmg` -- **Linux**: `WireTemperatureCalculator-Linux.AppImage` - -### 4. Manual Installation -```bash -# Professional development setup -python3.13 -m venv venv -source venv/bin/activate -pip install -r requirements.txt -python -m wire_temp_calc.main -``` - -## ๐ŸŽฏ Core Features - -### Wire Temperature Calculation -- **Multi-unit support**: AWG, SWG, mm, mils, inch -- **Length units**: mm, cm, inch, feet, meters, yards -- **Materials**: Nichrome, Stainless Steel, Kanthal -- **Precise calculations** with thermal equilibrium modeling -- **Visual charts** with color-coded temperature ranges - -### Foam Cutting System -- **10 professional foam types** with specific temperature ranges -- **Safety monitoring** with real-time warnings -- **Cutting speed optimization** (1-10 mm/s) -- **Fire risk assessment** (low/medium/high) -- **Visual safety indicators** on charts - -### Professional Interface -- **Modern GUI** with PySide6/Qt -- **Command line interface** for automation -- **Project management** with save/load -- **Export capabilities** (PDF, print) -- **Cross-platform consistency** - -### Safety Features -- **Temperature validation** against foam-specific limits -- **Toxic fume warnings** for dangerous temperatures -- **Ventilation requirements** based on application -- **Emergency procedures** and safety guidelines -- **Professional PPE recommendations** - -## ๐Ÿงช Testing & Quality Assurance - -### Comprehensive Test Suite -```bash -# Run all tests -pytest tests/ --cov=src/wire_temp_calc --cov-report=term - -# Specific test categories -pytest tests/test_foam_cutting.py # Foam cutting tests -pytest tests/test_unit_conversions.py # Unit conversion tests -pytest tests/test_safety_features.py # Safety system tests -``` - -### Quality Metrics -- **Code Coverage**: >80% with comprehensive test suite -- **Performance**: <1ms temperature calculations -- **Cross-platform**: Tested on Windows, macOS, Linux -- **Safety Validation**: All foam types tested with proper ranges - -### CI/CD Pipeline -- **Automated testing** on push/PR -- **Multi-platform builds** for releases -- **PyPI publishing** for package distribution -- **GitHub releases** with executable packages - -## ๐Ÿ“ฆ Distribution & Packaging - -### PyPI Package -- **Professional package name**: `wire-temperature-calculator` -- **Version management**: Semantic versioning -- **Dependencies**: Properly specified and tested -- **Entry points**: Both GUI and CLI interfaces - -### Executable Packages -- **Windows**: Professional installer with shortcuts -- **macOS**: DMG package with app bundle -- **Linux**: AppImage for universal compatibility - -### GitHub Releases -- **Automated releases** via GitHub Actions -- **Multi-platform executables** for each release -- **Professional release notes** with installation instructions - -## ๐Ÿ“š Documentation - -### Professional Documentation -- **Installation Guide**: Platform-specific instructions -- **User Guide**: Complete feature documentation -- **API Reference**: Developer documentation -- **Safety Guidelines**: Professional safety information -- **Examples**: Real-world usage scenarios - -### GitHub Integration -- **Professional README**: Complete with badges and features -- **Contributing Guidelines**: Clear contribution process -- **Issue Templates**: Structured bug reports and features -- **Code of Conduct**: Professional community standards - -## ๐Ÿ›ก๏ธ Safety & Compliance - -### Professional Safety Standards -- **Foam-specific temperature limits** with scientific backing -- **Fire risk assessment** based on material properties -- **Toxic fume warnings** for decomposition temperatures -- **Emergency procedures** for different scenarios -- **Professional PPE recommendations** - -### Regulatory Compliance -- **Material safety data** integration -- **Workplace safety guidelines** -- **Environmental considerations** -- **Professional liability coverage** - -## ๐Ÿค Community & Support - -### Professional Community -- **GitHub Discussions**: Feature requests and questions -- **Issue Tracking**: Structured bug reporting -- **Contribution Process**: Clear guidelines for contributors -- **Recognition System**: Contributor acknowledgment - -### Support Channels -- **GitHub Issues**: Technical support -- **Email Support**: security@wiretempcalc.com -- **Documentation**: Comprehensive help system -- **Examples**: Real-world usage guidance - -## ๐Ÿ† Professional Recognition - -### Industry Applications -- **RC Aircraft Building**: Professional foam wing construction -- **Craft & Hobby**: Safe foam cutting for makers -- **Industrial**: Insulation and packaging applications -- **Educational**: STEM education and research - -### Quality Assurance -- **Professional testing** with real-world scenarios -- **Safety validation** by domain experts -- **Performance optimization** for production use -- **User experience** refined through feedback - -## ๐Ÿš€ Ready for Production - -### Enterprise Features -- **Professional packaging** with proper versioning -- **Cross-platform deployment** with native installers -- **Comprehensive documentation** for enterprise use -- **Safety compliance** for professional environments -- **Support infrastructure** for commercial deployment - -### Commercial Readiness -- **MIT License** for commercial use -- **Professional support** available -- **Custom development** options -- **Enterprise integration** capabilities -- **Training and consulting** services - ---- - -## ๐Ÿ“‹ GitHub Repository Checklist - -โœ… **Repository Setup** -- Professional README with badges and features -- MIT License for commercial use -- Contributing guidelines for community -- Code of conduct for professional standards -- Issue templates for structured reporting - -โœ… **Code Quality** -- Comprehensive test suite with >80% coverage -- CI/CD pipeline with automated testing -- Code formatting with Black -- Linting with flake8 -- Type checking with mypy - -โœ… **Documentation** -- Complete installation guides -- Comprehensive user documentation -- API reference for developers -- Safety guidelines for professional use -- Examples and tutorials - -โœ… **Distribution** -- PyPI package for Python distribution -- Cross-platform executables for easy installation -- GitHub releases with automated builds -- Professional installers for each platform - -โœ… **Community** -- GitHub Discussions for community engagement -- Professional issue tracking -- Clear contribution process -- Recognition system for contributors - -**๐ŸŽฏ Status: READY FOR GITHUB!** - -This project is now a **professional, enterprise-grade software package** ready for: -- โœ… GitHub repository creation -- โœ… Community contribution -- โœ… Commercial distribution -- โœ… Professional deployment -- โœ… Enterprise integration - -The Wire Temperature Calculator represents **professional software development standards** with comprehensive features, safety systems, and cross-platform support for both hobbyist and commercial applications. \ No newline at end of file +HotWire is an alpha wire-temperature estimation application with CLI and PySide6 GUI. Current features and installation instructions are in the [README](README.md) and [user guide](docs/user-guide.md). The [model validation note](docs/model-validation.md) lists assumptions and unresolved safety and measurement work. See the [release checklist](docs/release-checklist.md) for the actual release state. diff --git a/README.md b/README.md index 9dfcfd2..6b908dd 100644 --- a/README.md +++ b/README.md @@ -1,240 +1,62 @@ -# ๐Ÿ”ฅ Wire Temperature Calculator +# HotWire โ€” Wire Temperature Calculator -[![CI/CD Pipeline](https://github.com/Monotoba/HotWire/actions/workflows/ci.yml/badge.svg)](https://github.com/Monotoba/HotWire/actions/workflows/ci.yml) -[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/) -[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +[![CI](https://github.com/Monotoba/HotWire/actions/workflows/ci.yml/badge.svg)](https://github.com/Monotoba/HotWire/actions/workflows/ci.yml) +[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/) +[![License: MIT](https://img.shields.io/badge/license-MIT-yellow)](LICENSE) +[![Status: alpha](https://img.shields.io/badge/status-alpha-orange)](docs/model-validation.md) -> **Project status:** Work in progress. The current CI and test suite need repair; no verified PyPI release or packaged desktop download is available yet. Calculated temperatures and foam guidance are estimates, not validated safety limits. +A Python CLI and PySide6 desktop app for **estimating** steady-state wire temperature from current, diameter, length, and material. It also displays experimental foam cutting ranges. These ranges are **not safety limits**. -> **Professional-grade wire temperature calculator with comprehensive foam cutting capabilities** +## Status and scope -## ๐ŸŽฏ Overview +This is alpha software. The wire model has been checked for physical consistency and against published room-temperature resistivity for two representative alloys; **its temperature predictions have not been calibrated against measured wire temperatures**. The foam database has not been verified against manufacturer safety data sheets. Do not use the output to determine permissible exposure, ventilation adequacy, fire safety, or a safe operating temperature. See [model validation and limitations](docs/model-validation.md). -The Wire Temperature Calculator is a sophisticated application for calculating wire temperatures and optimizing foam cutting operations. It combines precise thermal calculations with comprehensive safety monitoring, making it ideal for both hobbyists and professionals. +The app supports Nichrome, Kanthal, and a generic stainless estimate; AWG, SWG, mm, mils, and inches for wire size; and mm, cm, inches, feet, metres, and yards for length. It can display a temperature chart, save/load JSON projects, and export/print a chart. The CLI can calculate one current or an explicit range, list foam types, and display preliminary foam information. -### โœจ Key Features +## Install from source -- **๐ŸŒก๏ธ Multi-Unit Support**: AWG, SWG, mm, mils, inch for wire gauges -- **๐Ÿ“ Length Units**: mm, cm, inch, feet, meters, yards -- **๐Ÿ”ง Materials**: Nichrome, Stainless Steel, Kanthal -- **๐Ÿงฝ Foam Cutting**: 10 professional foam types with safety monitoring -- **๐Ÿ“Š Visualization**: Color-coded charts with safety indicators -- **๐Ÿ“„ Export**: PDF and print support -- **๐Ÿ’พ Project Management**: Save/load configurations -- **๐Ÿ›ก๏ธ Safety First**: Comprehensive safety monitoring and warnings +Python 3.10 or newer is required. From a checkout: -## ๐Ÿš€ Quick Start - -### GUI Application -```bash -python -m wire_temp_calc.main -``` - -### Command Line Interface -```bash -# Calculate temperature for 22 AWG nichrome wire -wire-temp-calc --gauge 22 --material nichrome --current 1 - -# Foam cutting with EPP foam -wire-temp-calc --foam EPP --wire-diameter 0.644 --cutting-speed 5 - -# List all supported foam types -wire-temp-calc --list-foams -``` - -## ๐Ÿ“ฆ Installation - -### Install from source ```bash git clone https://github.com/Monotoba/HotWire.git cd HotWire python3 -m venv .venv -source .venv/bin/activate # Linux/macOS; on Windows use .venv\Scripts\activate +source .venv/bin/activate # Windows PowerShell: .venv\Scripts\Activate.ps1 python -m pip install -e . -wire-temp-calc --help -``` - -### Manual Installation -```bash -# Create virtual environment -python3 -m venv .venv -source .venv/bin/activate # Linux/macOS -# On Windows use .venv\Scripts\activate - -# Install dependencies -pip install -e . - -# Run application -python -m wire_temp_calc.main -``` - -## ๐ŸŽฏ Core Capabilities - -### Wire Temperature Calculation -- **Precise thermal modeling** with material-specific properties -- **Iterative temperature solving** accounting for resistance changes -- **Multi-current range analysis** with customizable steps -- **Real-time safety validation** with visual feedback - -### Foam Cutting Optimization -- **10 professional foam types** with specific temperature ranges -- **Automatic optimal temperature calculation** based on wire and foam properties -- **Cutting speed recommendations** for different applications -- **Safety monitoring** with real-time warnings - -### Unit System -- **Bidirectional conversion** between any supported units -- **Precision preservation** across conversions -- **Flexible input methods** - enter values in any unit -- **Professional display** with appropriate unit formatting - -### Safety Features -- **Temperature range validation** for each foam type -- **Fire risk assessment** (low/medium/high) -- **Toxic fume warnings** for dangerous temperatures -- **Ventilation and PPE recommendations** -- **Emergency procedure guidelines** - -## ๐Ÿงฝ Supported Foam Types - -| Foam | Temperature Range | Best For | Characteristics | -|------|------------------|----------|-----------------| -| **EPP** | 220-260ยฐC | RC Aircraft | Durable, impact resistant | -| **EPS** | 180-220ยฐC | Packaging | Lightweight, easy to cut | -| **EVA** | 190-230ยฐC | Crafts | Soft, flexible | -| **XPS** | 200-240ยฐC | Insulation | Dense, closed-cell | -| **DEPRON** | 180-220ยฐC | RC Models | Thin, rigid sheets | -| **FOAM_BOARD** | 160-200ยฐC | Presentations | Paper-faced | -| **MEMORY** | 150-190ยฐC | Cushioning | Temperature-sensitive | -| **NEOPRENE** | 180-220ยฐC | Weather Sealing | Weather-resistant | -| **PU** | 170-210ยฐC | Upholstery | Versatile | -| **EPE** | 200-240ยฐC | Packaging | Flexible, cushioning | - -## ๐Ÿ“Š Example Usage - -### RC Aircraft Building -```bash -# EPP wing construction with 22 AWG wire -wire-temp-calc --foam EPP --gauge 22 --material nichrome --length 3 --cutting-speed 5 -# Output: Optimal temperature: 240ยฐC, Fire risk: medium, Ventilation: Required -``` - -### Craft Projects -```bash -# EPS foam board cutting -wire-temp-calc --foam FOAM_BOARD --wire-diameter 0.5 --cutting-speed 2 -# Output: Optimal temperature: 180ยฐC, Fire risk: low, Ventilation: Not required -``` - -### Industrial Applications -```bash -# XPS insulation cutting with safety check -wire-temp-calc --safety-info XPS 250 -# Output: WARNING: Temperature too high! Maximum: 240ยฐC ``` -## ๐Ÿ›ก๏ธ Safety Features +Launch the GUI with `wire-temp-gui` or `python -m wire_temp_calc.main`. A desktop session is required. Run `wire-temp-calc --help` for CLI options. No PyPI or native installer availability is promised by this source installation guide. -### Automatic Safety Monitoring -- **Real-time temperature validation** against foam-specific limits -- **Visual danger indicators** on charts (red zones) -- **Fire risk assessment** with appropriate warnings -- **Toxic fume alerts** for decomposition temperatures - -### Professional Safety Standards -- **Ventilation requirements** based on foam type and temperature -- **Personal protective equipment** recommendations -- **Emergency procedures** for different scenarios -- **Workspace safety guidelines** with volume considerations - -## ๐Ÿงช Testing - -The project includes comprehensive test coverage: +## Examples ```bash -# Run all tests -pytest tests/ --cov=src/wire_temp_calc --cov-report=term - -# Run specific test suite -pytest tests/test_foam_cutting.py - -# Run with coverage report -pytest tests/ --cov-report=html -``` - -**Test Coverage:** -- โœ… Unit conversion accuracy tests -- โœ… Physics behavior verification -- โœ… Safety system validation -- โœ… GUI functionality tests -- โœ… Cross-platform compatibility - -## ๐Ÿ—๏ธ Architecture - -``` -wire-temperature-calculator/ -โ”œโ”€โ”€ src/wire_temp_calc/ # Core package -โ”‚ โ”œโ”€โ”€ wire_temp_calculator.py # Temperature calculations -โ”‚ โ”œโ”€โ”€ foam_cutting.py # Foam cutting logic -โ”‚ โ”œโ”€โ”€ unit_conversions.py # Unit conversion system -โ”‚ โ”œโ”€โ”€ main_window.py # GUI implementation -โ”‚ โ””โ”€โ”€ cli.py # Command line interface -โ”œโ”€โ”€ tests/ # Comprehensive test suite -โ”œโ”€โ”€ docs/ # Professional documentation -โ”œโ”€โ”€ scripts/ # Utility scripts -โ””โ”€โ”€ dist/ # Distribution packages +wire-temp-calc --gauge 22 --material nichrome --length 2 --length-unit feet --current 1 +wire-temp-calc --current-start 0.1 --current-end 5 --current-step 0.1 +wire-temp-calc --list-foams +wire-temp-calc --safety-info EPS 250 ``` -## ๐Ÿค Contributing +The CLI's foam information is heuristic. Ventilation is recommended for hot-wire cutting regardless of whether the modeled temperature falls inside a listed cutting range. Read the material-specific safety data sheet and use suitable engineering controls. -We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. +## Development and release -### Quick Contribution Guide ```bash -# Fork and clone -git clone https://github.com/Monotoba/HotWire.git -cd HotWire - -# Set up development environment -python3 -m venv .venv -source .venv/bin/activate -python -m pip install -e ".[dev]" - -# Make changes and test -pytest tests/ -black src/ -flake8 src/ - -# Submit pull request +python -m pip install -e '.[dev]' +QT_QPA_PLATFORM=offscreen pytest tests/ # Linux headless test environment +black --check src/ +mypy src/ --ignore-missing-imports +python -m build +python -m twine check dist/* ``` -## ๐Ÿ“„ Documentation - -Comprehensive documentation available at: -- **[Installation Guide](docs/installation/index.md)** - Detailed setup instructions -- **[User Guide](docs/user-guide.md)** - Complete usage guide - -## ๐Ÿ› Issues & Support - -- **Bug Reports and Feature Requests**: [GitHub Issues](https://github.com/Monotoba/HotWire/issues) - -## ๐Ÿ“œ License - -This project is licensed under the MIT License - see [LICENSE](LICENSE) file for details. - -## ๐Ÿ™ Acknowledgments - -- **PySide6 Team** for the excellent Qt bindings -- **PyQtGraph Team** for the visualization library -- **Contributors** for their valuable input and testing -- **RC Aircraft Community** for foam cutting expertise - ---- - -
+The current GitHub Actions matrix tests Python 3.10โ€“3.13 on Linux, Windows, and macOS and builds source and wheel artifacts. [Release preparation](docs/release-checklist.md) records the remaining checks. A green CI build is not a validation of measured thermal performance. -**Made with โค๏ธ for makers, hobbyists, and professionals worldwide** +## Documentation and contribution -[โญ Star this repo](https://github.com/Monotoba/HotWire) if you find it useful! +- [Installation](docs/installation/index.md) +- [User guide](docs/user-guide.md) +- [Model validation and limitations](docs/model-validation.md) +- [Release checklist](docs/release-checklist.md) +- [Contributing](CONTRIBUTING.md) and [issues](https://github.com/Monotoba/HotWire/issues) -
+HotWire is licensed under the [MIT License](LICENSE). diff --git a/USAGE.md b/USAGE.md index fb37aab..4a8247d 100644 --- a/USAGE.md +++ b/USAGE.md @@ -1,105 +1,3 @@ -# Wire Temperature Calculator - Quick Start Guide +# Usage -## Installation - -### Option 1: Automated Installation (Recommended) -```bash -./install.sh -``` - -### Option 2: Manual Installation -```bash -# Create virtual environment -python3 -m venv venv -source venv/bin/activate - -# Install dependencies -pip install -r requirements.txt -``` - -## Running the Application - -### Method 1: Using the launcher -```bash -./launch.py -``` - -### Method 2: Direct Python execution -```bash -python main_window.py -``` - -## Basic Usage - -1. **Select Wire Parameters**: - - Choose wire type (Nichrome or Stainless Steel) - - Select wire gauge (20-30 AWG) - - Enter wire length (feet or meters) - -2. **Set Current Range**: - - Start current: 0.1A (default) - - End current: 5.0A (default) - - Step: 0.1A (default) - -3. **Calculate**: - - Click "Calculate" button - - View color-coded chart (darker = colder) - - Check results table for exact values - -## Advanced Features - -### Custom Resistance -- Enter custom resistance per foot in the resistance field -- Leave blank to use calculated values - -### Project Files -- **Save**: Ctrl+S to save current configuration -- **Open**: Ctrl+O to load saved project -- **New**: Ctrl+N to start fresh - -### Export Options -- **PDF Export**: Ctrl+E to export chart as PDF -- **Print**: Ctrl+P to print chart (A4 landscape) - -## Color Coding - -The chart uses a blue-to-red gradient: -- **Blue/Dark**: Lower temperatures (colder) -- **Red/Bright**: Higher temperatures (hotter) - -## Example Results - -For 22 AWG Nichrome wire, 2 feet long: -- 1.0A โ†’ ~111ยฐC -- 2.0A โ†’ ~273ยฐC -- 3.0A โ†’ ~460ยฐC - -## Troubleshooting - -### Application won't start -- Check Python version: `python3 --version` (requires 3.10+) -- Install dependencies: `pip install -r requirements.txt` - -### Charts not displaying -- Ensure all input values are valid numbers -- Check that current range is logical (start < end) - -### Print/PDF issues -- Verify system has printer configured -- Check file permissions for PDF export location - -## Technical Notes - -- Calculations assume 20ยฐC ambient temperature -- Uses thermal equilibrium equations -- Considers both convective and radiative heat transfer -- Iterative solution for temperature-dependent resistance - -## Keyboard Shortcuts - -- **Ctrl+N**: New project -- **Ctrl+O**: Open project -- **Ctrl+S**: Save project -- **Ctrl+E**: Export PDF -- **Ctrl+P**: Print -- **Ctrl+Q**: Quit \ No newline at end of file +The maintained [user guide](docs/user-guide.md) covers the CLI, GUI, projects, and PDF export. For model assumptions and safety limitations, read [model validation](docs/model-validation.md). diff --git a/activate_and_run.bat b/activate_and_run.bat index bdcca6d..3e1316b 100644 --- a/activate_and_run.bat +++ b/activate_and_run.bat @@ -1,36 +1,7 @@ @echo off -REM Activation and run script for Wire Temperature Calculator (Windows) -REM This script activates the Python 3.13 venv and runs the application - -echo Wire Temperature Calculator - Python 3.13 -echo ========================================= - -REM Check if venv exists -if not exist "venv" ( - echo Virtual environment not found. Creating Python 3.13 venv... - python3.13 -m venv venv +cd /d "%~dp0" +if not exist ".venv\Scripts\wire-temp-gui.exe" ( + echo Run install.bat first, or follow docs\installation\index.md. + exit /b 1 ) - -REM Activate virtual environment -echo Activating Python 3.13 virtual environment... -call venv\Scripts\activate.bat - -REM Verify Python version -echo Python version: -python --version - -REM Check if dependencies are installed -python -c "import PySide6, pyqtgraph, numpy" 2>nul -if errorlevel 1 ( - echo Installing dependencies... - pip install --upgrade pip - pip install -r requirements.txt -) - -REM Run the application -echo Starting Wire Temperature Calculator... -echo. -python launch.py - -REM Deactivate virtual environment when done -deactivate \ No newline at end of file +.venv\Scripts\wire-temp-gui.exe diff --git a/activate_and_run.sh b/activate_and_run.sh old mode 100755 new mode 100644 index e6b9177..258264c --- a/activate_and_run.sh +++ b/activate_and_run.sh @@ -1,36 +1,8 @@ -#!/bin/bash - -# Activation and run script for Wire Temperature Calculator -# This script activates the Python 3.13 venv and runs the application - -echo "Wire Temperature Calculator - Python 3.13" -echo "=========================================" - -# Check if venv exists and is Python 3.13 -if [ ! -d "venv" ] || [ ! -f "venv/bin/python" ] || ! "venv/bin/python" --version | grep -q "3.13"; then - echo "Creating/Updating Python 3.13 virtual environment..." - rm -rf venv # Remove old venv if it exists - python3.13 -m venv venv +#!/usr/bin/env bash +set -euo pipefail +cd "$(dirname "$0")" +if [ ! -x .venv/bin/wire-temp-gui ]; then + echo 'Run ./install.sh first, or follow docs/installation/index.md.' >&2 + exit 1 fi - -# Activate virtual environment -echo "Activating Python 3.13 virtual environment..." -. venv/bin/activate - -# Verify Python version -echo "Python version: $(python --version)" - -# Check if dependencies are installed -if ! python -c "import PySide6, pyqtgraph, numpy" 2>/dev/null; then - echo "Installing dependencies..." - pip install --upgrade pip - pip install -r requirements.txt -fi - -# Run the application -echo "Starting Wire Temperature Calculator..." -echo "" -python launch.py - -# Deactivate virtual environment when done -deactivate \ No newline at end of file +exec .venv/bin/wire-temp-gui diff --git a/docs/index.md b/docs/index.md index f4e2651..6ffd514 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,90 +1,9 @@ -# Wire Temperature Calculator Documentation +# HotWire documentation -## Overview +HotWire estimates the steady-state temperature of a wire in still air and provides preliminary foam cutting ranges. It does not measure temperature or certify that a setup is safe. -The Wire Temperature Calculator is a professional-grade application for calculating wire temperatures and foam cutting parameters. It supports multiple wire gauge units, length units, and foam types with comprehensive safety monitoring. - -## Features - -### Core Capabilities -- **Multi-unit support**: AWG, SWG, mm, mils, inch for wire gauges -- **Length units**: mm, cm, inch, feet, meters, yards -- **Materials**: Nichrome, Stainless Steel, Kanthal -- **Foam cutting**: 10 professional foam types with safety monitoring -- **Visualization**: Color-coded charts with safety indicators -- **Export**: PDF and print support -- **Project management**: Save/load configurations - -### Safety Features -- Real-time temperature validation -- Fire risk assessment -- Toxic fume warnings -- Ventilation requirements -- PPE recommendations - -## Quick Start - -### GUI Application -```bash -# Run the GUI application -./activate_and_run.sh -``` - -### Command Line Interface -```bash -# Calculate temperature for 22 AWG nichrome wire at 1A -wire-temp-calc --gauge 22 --gauge-unit AWG --material nichrome --length 2 --length-unit feet --current 1 - -# Foam cutting with EPP foam -wire-temp-calc --foam EPP --wire-diameter 0.644 --cutting-speed 5 -``` - -## Installation - -### Automated Installation (Recommended) -```bash -# Clone the repository -git clone https://github.com/yourusername/wire-temperature-calculator.git -cd wire-temperature-calculator - -# Run automated installer -./install.sh -``` - -### Manual Installation -```bash -# Create virtual environment -python3.13 -m venv venv -source venv/bin/activate # Linux/Mac -# or -venv\Scripts\activate.bat # Windows - -# Install dependencies -pip install -r requirements.txt - -# Run application -python -m wire_temp_calc.main -``` - -## Documentation Sections - -- [Installation Guide](installation/index.md) - Detailed installation instructions -- [User Guide](user-guide.md) - Complete usage guide -- [API Reference](api/index.md) - Developer API documentation -- [Examples](examples/index.md) - Usage examples and tutorials -- [Safety Guidelines](safety.md) - Important safety information -- [Troubleshooting](troubleshooting.md) - Common issues and solutions - -## Support - -- **Issues**: [GitHub Issues](https://github.com/yourusername/wire-temperature-calculator/issues) -- **Discussions**: [GitHub Discussions](https://github.com/yourusername/wire-temperature-calculator/discussions) -- **Email**: support@wiretempcalc.com - -## License - -This project is licensed under the MIT License - see the [LICENSE](../LICENSE) file for details. - -## Contributing - -We welcome contributions! Please see [CONTRIBUTING.md](../CONTRIBUTING.md) for guidelines. \ No newline at end of file +- [Install from source](installation/index.md) +- [Use the CLI and GUI](user-guide.md) +- [Model assumptions, validation, and safety limits](model-validation.md) +- [Alpha release checklist](release-checklist.md) +- [Report a problem](https://github.com/Monotoba/HotWire/issues) diff --git a/docs/installation/index.md b/docs/installation/index.md index 0a70234..0889f1e 100644 --- a/docs/installation/index.md +++ b/docs/installation/index.md @@ -1,235 +1,19 @@ -# Installation Guide +# Installation from source -## System Requirements +Requires Python 3.10 or newer. The GUI also needs a working desktop display and Qt runtime libraries appropriate to your operating system. Source installation has been exercised in CI on Linux, macOS, and Windows; individual desktop configurations can differ. -### Minimum Requirements -- **Python**: 3.10 or higher (Python 3.13 recommended) -- **Operating System**: Windows 10+, macOS 10.14+, Linux (Ubuntu 18.04+) -- **Memory**: 4GB RAM minimum, 8GB recommended -- **Storage**: 500MB free space -- **Display**: 1024x768 resolution minimum - -### Recommended Requirements -- **Python**: 3.13+ with latest updates -- **Memory**: 8GB RAM or more -- **Storage**: 1GB free space -- **Display**: 1920x1080 resolution or higher - -## Installation Methods - -### Method 1: Automated Installation (Recommended) - -**Linux/macOS:** -```bash -# Clone the repository -git clone https://github.com/yourusername/wire-temperature-calculator.git -cd wire-temperature-calculator - -# Make installer executable -chmod +x install.sh - -# Run automated installer -./install.sh - -# Launch application -./activate_and_run.sh -``` - -**Windows:** -```cmd -# Clone the repository -git clone https://github.com/yourusername/wire-temperature-calculator.git -cd wire-temperature-calculator - -# Run automated installer -install.bat - -# Launch application -activate_and_run.bat -``` - -### Method 2: Manual Installation - -**Step 1: Install Python** -Download and install Python 3.13+ from [python.org](https://www.python.org/downloads/) - -**Step 2: Clone Repository** -```bash -git clone https://github.com/yourusername/wire-temperature-calculator.git -cd wire-temperature-calculator -``` - -**Step 3: Create Virtual Environment** -```bash -# Linux/macOS -python3.13 -m venv venv -source venv/bin/activate - -# Windows -python -m venv venv -venv\Scripts\activate -``` - -**Step 4: Install Dependencies** -```bash -pip install --upgrade pip -pip install -r requirements.txt -``` - -**Step 5: Run Application** ```bash -# GUI Application -python -m wire_temp_calc.main - -# Command Line Interface -python -m wire_temp_calc.cli --help -``` - -### Method 3: Package Installation - -**From PyPI (when published):** -```bash -pip install wire-temperature-calculator +git clone https://github.com/Monotoba/HotWire.git +cd HotWire +python3 -m venv .venv +source .venv/bin/activate +python -m pip install -e . wire-temp-calc --help +wire-temp-gui ``` -**From Source Distribution:** -```bash -# Build from source -python setup.py sdist bdist_wheel - -# Install the package -pip install dist/wire_temperature_calculator-2.0.0-py3-none-any.whl -``` - -## Platform-Specific Instructions - -### Windows - -**Prerequisites:** -- Visual C++ Redistributable (usually included with Python) -- Windows 10 or higher - -**Installation Notes:** -- Run PowerShell as Administrator for system-wide installation -- Windows Defender may flag the application - add to exclusions if needed -- Use Windows Terminal for best experience - -### macOS - -**Prerequisites:** -- Xcode Command Line Tools: `xcode-select --install` -- Homebrew (recommended): `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"` - -**Installation Notes:** -- May need to allow app in Security & Privacy settings -- Use Homebrew Python for best compatibility - -### Linux - -**Ubuntu/Debian:** -```bash -sudo apt update -sudo apt install python3.13 python3.13-venv python3-pip -``` - -**Fedora/RHEL:** -```bash -sudo dnf install python3.13 python3-pip -``` - -**Arch Linux:** -```bash -sudo pacman -S python python-pip -``` - -## Verification - -### Test Installation -```bash -# Test basic functionality -python -m wire_temp_calc.cli --list-foams - -# Test temperature calculation -python -m wire_temp_calc.cli --gauge 22 --material nichrome --current 1 - -# Test GUI (if display available) -python -m wire_temp_calc.main -``` - -### Expected Output -``` -Supported Foam Types: -============================ -EPP | Expanded Polypropylene - High performance, multiple impacts - Temperature range: 220-260ยฐC - Cutting speed: medium - Fire risk: medium - -EPS | Expanded Polystyrene - Common white foam, easy to cut - Temperature range: 180-220ยฐC - Cutting speed: fast - Fire risk: medium -... -``` - -## Troubleshooting - -### Common Issues - -**1. Import Error: No module named 'PySide6'** -```bash -# Solution: Reinstall requirements -pip install --force-reinstall -r requirements.txt -``` - -**2. Permission Denied on install.sh** -```bash -chmod +x install.sh -./install.sh -``` - -**3. Virtual Environment Activation Fails** -```bash -# Try explicit Python version -python3.13 -m venv venv -source venv/bin/activate -``` - -**4. Display Issues on Linux** -```bash -# Install display dependencies -sudo apt install libgl1-mesa-glx libglib2.0-0 -``` - -### Getting Help - -If you encounter issues: - -1. Check the [Troubleshooting Guide](../troubleshooting.md) -2. Search [GitHub Issues](https://github.com/yourusername/wire-temperature-calculator/issues) -3. Create a new issue with: - - Your operating system and version - - Python version - - Complete error message - - Steps to reproduce - -## Uninstallation - -### Automated Uninstall -```bash -# Run uninstall script -./uninstall.sh -``` - -### Manual Uninstall -```bash -# Remove virtual environment -rm -rf venv +On Windows PowerShell use `py -m venv .venv`, `.venv\Scripts\Activate.ps1`, then the same `python -m pip install -e .` and commands. You can also run `python -m wire_temp_calc.main` in the activated environment. -# Remove application files -rm -rf wire-temperature-calculator +For development, install `python -m pip install -e '.[dev]'` and run `pytest tests/`. On Linux without a display, use `QT_QPA_PLATFORM=offscreen pytest tests/`. -# Remove configuration files -rm -rf ~/.config/WireTempCalc -``` \ No newline at end of file +The convenience scripts `install.sh`/`activate_and_run.sh` and `install.bat`/`activate_and_run.bat` use `.venv`. The POSIX script syntax has been checked; the Windows scripts still need a manual installation test. There is no verified PyPI release or packaged desktop installer at this time. Open an [issue](https://github.com/Monotoba/HotWire/issues) with your OS, Python version, and traceback if installation fails. diff --git a/docs/model-validation.md b/docs/model-validation.md new file mode 100644 index 0000000..1449529 --- /dev/null +++ b/docs/model-validation.md @@ -0,0 +1,31 @@ +# Model validation and limitations + +This page describes what was checked for the alpha version and what remains unverified. **No measured wire-temperature calibration or material-specific occupational exposure assessment has been performed.** + +## Wire model + +At a given current, the solver finds a steady-state temperature where `Iยฒ R(T)` equals estimated convection plus radiation from a cylindrical wire. It assumes ambient temperature 20 ยฐC, natural convection coefficient 10 W/(mยฒยทK), uniform wire temperature, fixed emissivity, and a temperature-dependent resistance approximation. It ignores support conduction, contacts, forced airflow, foam contact, transient heating, local hot spots, power-supply regulation, wire oxidation, and changes in emissivity. The solver stops if it cannot find equilibrium below 2000 ยฐC; this is a numerical bound, **not** a permissible material temperature. + +20 ยฐC resistivity inputs (ฮฉยทmmยฒ/m): + +| UI material | Model input | Evidence and limitation | +| --- | ---: | --- | +| Nichrome | 1.09 | [Kanthal Nikrothal 80 datasheet](https://www.kanthal.com/products/datasheets/material-datasheets/wire/resistance-heating-wire-and-resistance-wire/nikrothal-80/); the user's alloy may differ. | +| Kanthal | 1.45 | [Kanthal A-1 datasheet](https://prodshop.kanthal.com/en/products/datasheets/material-datasheets/wire/resistance-heating-wire-and-resistance-wire/kanthal_a_1/); other Kanthal grades may differ. | +| Stainless | 0.672 | Generic estimate retained pending selection and verification of a specific grade. | + +Manufacturer data constrain electrical resistivity, **not** the full temperature prediction. Temperature-dependent resistance, convection, and emissivity are approximations. A user-entered resistance per foot overrides the room-temperature resistance used in a GUI calculation. The formulas are tested for current monotonicity, equivalent unit inputs, and power balance; those are consistency checks, not measurement validation. + +**Before using the estimate to set hardware:** identify the exact wire alloy and dimensions, measure cold resistance and operating wire temperature with a suitable method over the intended current range, and record airflow and mounting. Compare measurements to predictions and revise the model or show uncertainty. Do not extrapolate beyond validated conditions. + +## Foam guidance + +The ten built-in foam ranges and speed adjustments are unverified heuristics. They are not decomposition temperatures, exposure limits, fire limits, or proof of safe cutting. The application does not measure smoke or airborne exposure and cannot determine ventilation adequacy from workspace volume or wire temperature. Use the exact foam product's safety data sheet and an appropriate exposure-control assessment. The [UK Health and Safety Executive's hot-wire cutting guidance](https://www.hse.gov.uk/plastics/fire-safety.htm#hot-wire) discusses overheating, fire, and fume hazards for flexible PU foam; its discussion is not a validation of HotWire's numbers for other foam products. + +The CLI and GUI retain preliminary warnings and risk categories for exploration, but a โ€œlowโ€ label cannot rule out hazardous fumes or fire. Ventilation is recommended regardless of the estimated cutting range. A physical wire temperature is not necessarily the temperature of the heated foam. Additional material-by-material evidence and emission measurements are required before using foam guidance for an operating procedure. + +## Validation performed + +- Automated tests: CLI behavior, GUI calculation and PDF smoke test, project round trip, equivalent units, current trend, power balance, and manufacturer room-temperature resistivity inputs. +- Source/wheel packaging and cross-platform CI are checked separately in the [release checklist](release-checklist.md). +- No wire thermometry, fume sampling, fire testing, installer usability testing, or print hardware testing has been performed. diff --git a/docs/release-checklist.md b/docs/release-checklist.md new file mode 100644 index 0000000..f65d5b9 --- /dev/null +++ b/docs/release-checklist.md @@ -0,0 +1,16 @@ +# Alpha release preparation + +Proposed version: `2.0.0a1`. Release scope: a **GitHub alpha source archive and Python wheel/source distribution**, with an explicit experimental-model notice. No PyPI publication or native desktop installer is included. + +## Gates + +- [x] Fix advertised CLI commands and cover success/error exits with command tests. +- [x] Smoke-test GUI chart, project round trip, and PDF output offscreen. +- [x] Check model monotonicity, unit equivalence, heat balance, and published room-temperature resistivity for representative alloys. +- [x] Document unvalidated temperature and foam safety claims. +- [ ] Confirm the release commit passes the complete Linux/Windows/macOS CI matrix. +- [x] Build sdist and wheel, pass `twine check`, and install the wheel in a clean Linux Python 3.12 environment; run CLI and headless GUI smoke checks. +- [ ] Manually test Windows installation and printing on an actual printer, if those paths are promoted as supported. +- [ ] Review release notes and tag `v2.0.0a1` after approval. + +No measured thermal or foam-exposure validation is claimed for this alpha. Any subsequent production-oriented release needs material-specific measurements and safety review. See [model validation](model-validation.md). diff --git a/docs/user-guide.md b/docs/user-guide.md index 795c696..f379a8a 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -1,235 +1,27 @@ -# User Guide +# User guide -## Getting Started +## Wire temperature estimate -### Launching the Application +Install from [source](installation/index.md), then run `wire-temp-gui`. Choose a wire material and diameter or gauge, wire length, and current range. Press **Calculate** to view a chart and results table. The model assumes 20 ยฐC ambient temperature, approximate natural convection, a fixed emissivity, and an isolated wire in still air. Clamps, airflow, contact with foam, and supply behavior can change the actual temperature. See [validation and limitations](model-validation.md). -**GUI Mode (Recommended):** -```bash -# Run the GUI application -./activate_and_run.sh -``` +CLI examples: -**Command Line Mode:** ```bash -# Basic temperature calculation wire-temp-calc --gauge 22 --material nichrome --current 1 - -# Foam cutting mode -wire-temp-calc --foam EPS --wire-diameter 0.644 --cutting-speed 5 +wire-temp-calc --current-start 0.1 --current-end 5 --current-step 0.1 +wire-temp-calc --list-units ``` -### Main Interface Overview - -![Main Interface](images/main_interface.png) - -The application interface consists of: - -1. **Wire Specifications Panel** (Top Left) - - Wire type selection - - Gauge size and unit input - - Length and unit input - - Optional resistance override - -2. **Current Range Panel** (Middle Left) - - Start, end, and step current values - - Default: 0.1A to 5.0A in 0.1A steps - -3. **Foam Cutting Panel** (Bottom Left) - - Foam type selector - - Cutting speed input - - Safety information display - -4. **Results Panel** (Top Right) - - Temperature vs current table - - Detailed numerical results - -5. **Chart Panel** (Bottom Right) - - Color-coded temperature chart - - Visual safety indicators - - Foam cutting zones - -## Basic Operations - -### 1. Simple Temperature Calculation - -**Step 1:** Select Wire Type -- Choose from: Nichrome, Stainless Steel, or Kanthal -- Default: Nichrome (most common for heating applications) - -**Step 2:** Enter Wire Size -- **AWG Mode**: Enter gauge number (e.g., 22 for 22 AWG) -- **Metric Mode**: Enter diameter in mm (e.g., 0.644 for 22 AWG equivalent) -- **Imperial Mode**: Enter diameter in mils or inches - -**Step 3:** Enter Wire Length -- Select appropriate unit from dropdown -- Common values: 2 feet, 24 inches, 0.61 meters - -**Step 4:** Set Current Range -- Default range works for most applications -- Adjust based on your power supply capabilities - -**Step 5:** Click Calculate -- Results appear in table and chart -- Chart shows temperature vs current relationship - -### 2. Foam Cutting Mode - -**Step 1:** Enable Foam Cutting -- Select foam type from dropdown -- Choose "None" to disable foam cutting mode - -**Step 2:** Select Foam Type -- **RC Aircraft**: EPP (durable), EPS (lightweight), DEPRON (thin sheets) -- **Craft Projects**: EVA (soft), FOAM_BOARD (presentation), MEMORY (cushioning) -- **Industrial**: XPS (insulation), PU (versatile), NEOPRENE (weather-resistant) - -**Step 3:** Set Cutting Speed -- **Slow (1-2 mm/s)**: Maximum precision, detailed work -- **Medium (5 mm/s)**: Standard cutting, balanced approach -- **Fast (8-10 mm/s)**: Production work, rough shapes - -**Step 4:** Review Safety Information -- Check optimal temperature range -- Note fire risk level -- Verify ventilation requirements - -**Step 5:** Calculate and Cut -- Application shows optimal temperature -- Chart displays safe cutting zone -- Visual indicators help maintain temperature - -## Advanced Features - -### Custom Resistance Values - -For non-standard wires: -1. Enter resistance per foot in ฮฉ/ft -2. Application will use this instead of calculated values -3. Useful for custom alloys or measured values - -### Project Management - -**Saving Projects:** -1. File โ†’ Save Project -2. Choose location and filename -3. All settings including foam type are saved - -**Loading Projects:** -1. File โ†’ Open Project -2. Select previously saved project file -3. All settings restored including foam cutting mode - -### Export Options - -**PDF Export:** -1. File โ†’ Export as PDF -2. Choose filename and location -3. Professional PDF with charts and data - -**Print:** -1. File โ†’ Print -2. Configure print settings -3. Optimized for A4 paper - -## Foam Cutting Guide - -### Foam Type Selection - -| Foam Type | Temperature Range | Best For | Characteristics | -|-----------|------------------|----------|-----------------| -| EPP | 220-260ยฐC | RC aircraft | Durable, impact resistant | -| EPS | 180-220ยฐC | Packaging | Lightweight, easy to cut | -| EVA | 190-230ยฐC | Crafts | Soft, flexible | -| XPS | 200-240ยฐC | Insulation | Dense, closed-cell | -| DEPRON | 180-220ยฐC | RC models | Thin, rigid sheets | -| FOAM_BOARD | 160-200ยฐC | Presentations | Paper-faced | -| MEMORY | 150-190ยฐC | Cushioning | Temperature-sensitive | -| NEOPRENE | 180-220ยฐC | Weather sealing | Weather-resistant | - -### Cutting Speed Guidelines - -| Speed Range | Application | Notes | -|-------------|-------------|-------| -| 1-2 mm/s | Maximum precision | Slow, detailed cuts | -| 3-5 mm/s | Standard cutting | Balanced approach | -| 6-8 mm/s | Production work | Faster, less precise | -| 9-10 mm/s | Rough cutting | Fastest, rough finish | - -### Safety Guidelines - -**Always:** -- Work in well-ventilated area -- Have fire extinguisher nearby -- Wear safety glasses and gloves -- Start with lower temperatures -- Monitor for smoke or odors - -**Temperature Warnings:** -- **Green Zone**: Safe operating range -- **Yellow Zone**: Optimal cutting temperature -- **Red Zone**: Dangerous - risk of decomposition/toxic fumes - -**Emergency Procedures:** -- Turn off power immediately if smoke appears -- Ventilate area if strong odors detected -- Allow wire to cool before handling -- Have emergency contact information ready - -## Troubleshooting - -### Common Issues - -**Application Won't Start:** -1. Check Python version (3.10+ required) -2. Verify virtual environment is activated -3. Reinstall dependencies: `pip install -r requirements.txt` - -**Chart Not Displaying:** -1. Check display drivers are installed -2. Try different Qt backend: `export QT_QPA_PLATFORM=xcb` -3. Verify sufficient graphics memory - -**Incorrect Temperatures:** -1. Verify wire gauge and material selection -2. Check length units are correct -3. Ensure current values are realistic -4. Try with known wire specifications - -**Foam Cutting Issues:** -1. Verify foam type selection -2. Check wire diameter is appropriate -3. Ensure cutting speed is reasonable -4. Review safety warnings carefully - -### Getting Help +Use `--current` for a single value. Use one or more of `--current-start`, `--current-end`, and `--current-step` for a range (defaults 0.1, 5.0, and 0.1 respectively). Do not combine `--current` with range options. -1. Check this user guide first -2. Review the [troubleshooting guide](troubleshooting.md) -3. Search [GitHub Issues](https://github.com/yourusername/wire-temperature-calculator/issues) -4. Create new issue with complete details +## Projects and PDF -## Tips and Best Practices +After calculating in the GUI, use **File โ†’ Save Project** for a JSON file and **File โ†’ Open Project** to restore wire and current settings. The current project format does not preserve a custom cutting speed. Use **File โ†’ Export as PDF** to save the plotted chart or **File โ†’ Print** to open a system printer dialog. PDF export has an automated offscreen smoke test; printer hardware has not been tested. -### Wire Selection -- **Nichrome**: Best for most applications, consistent heating -- **Stainless Steel**: Good for corrosive environments -- **Kanthal**: Highest resistance, good for high temperatures +## Foam information -### Temperature Control -- Start with lower temperatures and increase gradually -- Allow wire to reach steady state before cutting -- Monitor temperature with infrared thermometer if available +Selecting a foam displays an **estimated cutting range**, not a safe exposure or fire threshold. The CLI provides `--safety-info EPS 250` for preliminary guidance. The foam type and actual product composition matter; consult the product safety data sheet. Do not rely on a low heuristic fire-risk label or an in-range result to omit ventilation. A temperature estimate describes an isolated wire, not the temperature or emissions of foam in contact with it. -### Foam Cutting -- Practice on scrap pieces first -- Use consistent cutting speed -- Keep wire perpendicular to foam surface -- Allow foam to cool before handling +Keep a hot wire supervised, prevent contact with flammables, and arrange suitable ventilation and fume control. See the [model and safety notes](model-validation.md) for sources and unresolved validation work. -### Maintenance -- Clean wire regularly to remove oxidation -- Check connections for corrosion -- Replace wire if resistance changes significantly -- Store in dry environment \ No newline at end of file +For bugs and feature requests, use [GitHub Issues](https://github.com/Monotoba/HotWire/issues). diff --git a/install.bat b/install.bat index 072681c..4358239 100644 --- a/install.bat +++ b/install.bat @@ -43,7 +43,7 @@ echo. REM Create virtual environment echo Creating virtual environment... -python -m venv venv +python -m venv .venv if %errorLevel% neq 0 ( echo ERROR: Failed to create virtual environment pause @@ -55,7 +55,7 @@ echo. REM Activate virtual environment echo Activating virtual environment... -call venv\Scripts\activate.bat +call .venv\Scripts\activate.bat if %errorLevel% neq 0 ( echo ERROR: Failed to activate virtual environment pause @@ -75,15 +75,15 @@ echo. REM Install requirements echo Installing dependencies... -if exist requirements.txt ( - pip install -r requirements.txt +if exist setup.py ( + python -m pip install -e . if %errorLevel% neq 0 ( echo ERROR: Failed to install dependencies pause exit /b 1 ) ) else ( - echo ERROR: requirements.txt not found + echo ERROR: package files not found pause exit /b 1 ) @@ -126,7 +126,7 @@ echo Creating uninstall script... ( echo @echo off echo echo Uninstalling Wire Temperature Calculator... -echo rmdir /s /q venv +echo rmdir /s /q .venv echo del "%USERPROFILE%\Desktop\Wire Temperature Calculator.lnk" 2^>nul echo del "%APPDATA%\Microsoft\Windows\Start Menu\Programs\Wire Temperature Calculator.lnk" 2^>nul echo echo Uninstallation complete! diff --git a/install.sh b/install.sh old mode 100755 new mode 100644 index 8b14afe..e1bfa63 --- a/install.sh +++ b/install.sh @@ -1,51 +1,10 @@ -#!/bin/bash - -# Installation script for Wire Temperature Calculator - -echo "Wire Temperature Calculator - Installation Script" -echo "=================================================" - -# Check Python version -python_version=$(python3 --version 2>&1 | awk '{print $2}' | cut -d. -f1,2) -required_version="3.10" - -if [ "$(printf '%s\n' "$required_version" "$python_version" | sort -V | head -n1)" != "$required_version" ]; then - echo "Error: Python 3.10 or higher is required. Found: $python_version" - exit 1 -fi - -echo "Python version check passed: $python_version" - -# Create virtual environment if it doesn't exist -if [ ! -d "venv" ]; then - echo "Creating virtual environment..." - python3 -m venv venv -fi - -# Activate virtual environment -echo "Activating virtual environment..." -source venv/bin/activate - -# Upgrade pip -echo "Upgrading pip..." -pip install --upgrade pip - -# Install requirements -echo "Installing dependencies..." -pip install -r requirements.txt - -# Make scripts executable -echo "Setting up executable permissions..." -chmod +x launch.py -chmod +x test_calculator.py - -echo "" -echo "Installation completed successfully!" -echo "" -echo "To run the application:" -echo " source venv/bin/activate" -echo " python launch.py" -echo "" -echo "Or simply:" -echo " ./launch.py" -echo "" \ No newline at end of file +#!/usr/bin/env bash +set -euo pipefail +cd "$(dirname "$0")" +python3 -c 'import sys; sys.exit(0 if sys.version_info >= (3, 10) else 1)' || { + echo 'Python 3.10 or newer is required' >&2 + exit 1 +} +python3 -m venv .venv +.venv/bin/python -m pip install -e . +echo 'Installed. Run ./activate_and_run.sh for the GUI or .venv/bin/wire-temp-calc --help for CLI.' diff --git a/setup.py b/setup.py index ef4a50e..16aa569 100644 --- a/setup.py +++ b/setup.py @@ -22,13 +22,13 @@ version = line.split("=")[1].strip().strip('"').strip("'") break else: - version = "2.0.0" + version = "2.0.0a1" setup( name="wire-temperature-calculator", version=version, author="Wire Temperature Calculator Team", - description="Professional wire temperature calculator with comprehensive foam cutting capabilities", + description="Experimental wire temperature estimator with a PySide6 GUI", long_description=long_description, long_description_content_type="text/markdown", url="https://github.com/Monotoba/HotWire", diff --git a/src/wire_temp_calc/__init__.py b/src/wire_temp_calc/__init__.py index e034786..49312ad 100644 --- a/src/wire_temp_calc/__init__.py +++ b/src/wire_temp_calc/__init__.py @@ -5,10 +5,10 @@ with support for multiple wire gauge units, length units, and foam types. """ -__version__ = "2.0.0" +__version__ = "2.0.0a1" __author__ = "Wire Temperature Calculator Team" -__email__ = "support@wiretempcalc.com" -__description__ = "Professional wire temperature and foam cutting calculator" +__email__ = "" +__description__ = "Experimental wire temperature estimator" from .wire_temp_calculator import ( WireTemperatureCalculator, diff --git a/src/wire_temp_calc/foam_cutting.py b/src/wire_temp_calc/foam_cutting.py index ec175d2..3041de8 100644 --- a/src/wire_temp_calc/foam_cutting.py +++ b/src/wire_temp_calc/foam_cutting.py @@ -286,7 +286,7 @@ def get_safety_warning( if temperature_celsius < foam.min_temp_celsius: return f"Temperature too low for {foam.name}. May not cut effectively. Recommended: {foam.min_temp_celsius}-{foam.max_temp_celsius}ยฐC." elif temperature_celsius > foam.max_temp_celsius: - return f"WARNING: Temperature too high for {foam.name}! Risk of decomposition and toxic fumes. Maximum: {foam.max_temp_celsius}ยฐC." + return f"WARNING: Above the modeled cutting range for {foam.name}; overheating can increase fume and fire hazards. Modeled upper bound: {foam.max_temp_celsius}ยฐC. Consult the material safety data sheet." elif temperature_celsius > foam.optimal_temp_celsius + 10: return f"Temperature above optimal for {foam.name}. Consider reducing to {foam.optimal_temp_celsius}ยฐC for cleaner cuts." @@ -446,7 +446,8 @@ def get_safety_recommendations( "safety_warning": self.foam_db.get_safety_warning( foam_type, wire_temperature ), - "ventilation_required": wire_temperature > foam.optimal_temp_celsius + 10, + # A temperature threshold cannot establish that fume exposure is safe. + "ventilation_required": True, "fume_extraction_recommended": wire_temperature > foam.max_temp_celsius - 20, "fire_risk_level": self._assess_fire_risk(foam_type, wire_temperature), diff --git a/src/wire_temp_calc/main.py b/src/wire_temp_calc/main.py index d856626..08dc107 100644 --- a/src/wire_temp_calc/main.py +++ b/src/wire_temp_calc/main.py @@ -20,7 +20,9 @@ def main(): # Set application properties app.setApplicationName("Wire Temperature Calculator") - app.setApplicationVersion("2.0.0") + from . import __version__ + + app.setApplicationVersion(__version__) app.setOrganizationName("WireTempCalc") app.setOrganizationDomain("wiretempcalc.com") diff --git a/src/wire_temp_calc/main_window.py b/src/wire_temp_calc/main_window.py index e32ad01..a5cb4ea 100644 --- a/src/wire_temp_calc/main_window.py +++ b/src/wire_temp_calc/main_window.py @@ -146,14 +146,14 @@ def add_foam_temperature_ranges(self, foam, min_current: float, max_current: flo y_opt = foam.optimal_temp_celsius y_max = foam.max_temp_celsius - # Safe range (green background) - safe_range = pg.LinearRegionItem( + # This is an estimated cutting range, not a certified safety zone. + cutting_range = pg.LinearRegionItem( values=[y_min, y_max], orientation="horizontal", - brush=(0, 255, 0, 30), # Green with transparency - pen={"color": (0, 255, 0, 100), "width": 1}, + brush=(0, 100, 255, 30), + pen={"color": (0, 100, 255, 100), "width": 1}, ) - self.plot_widget.addItem(safe_range) + self.plot_widget.addItem(cutting_range) # Optimal range (yellow background, narrower) opt_range = pg.LinearRegionItem( @@ -868,10 +868,10 @@ def show_about(self): """Show about dialog""" about_text = """

Wire Temperature Calculator

-

Version 1.0

+

Alpha version 2.0.0a1 โ€” experimental estimates

This application calculates wire temperature based on current, wire type, and physical properties.

-

Supports Nichrome and Stainless Steel wires in various gauges.

+

Supports Nichrome, Kanthal, and a generic stainless estimate.

ยฉ 2024 - Open Source Application

""" diff --git a/src/wire_temp_calc/wire_temp_calculator.py b/src/wire_temp_calc/wire_temp_calculator.py index f4282fe..f57500f 100644 --- a/src/wire_temp_calc/wire_temp_calculator.py +++ b/src/wire_temp_calc/wire_temp_calculator.py @@ -78,6 +78,15 @@ class WireTemperatureCalculator: "copper": 1.0, # Copper baseline } + # Representative 20ยฐC resistivity in ฮฉยทmmยฒ/m. Nichrome 80 and Kanthal A-1 + # values are from their manufacturer datasheets; stainless is an estimate + # because alloy grade and condition are not specified by the UI. + MATERIAL_RESISTIVITY = { + "nichrome": 1.09, + "kanthal": 1.45, + "stainless": 0.672, + } + def __init__(self): self.ambient_temp = 20.0 # ยฐC self.foam_db = FoamCuttingDatabase() @@ -96,30 +105,34 @@ def calculate_temperature( Returns: Temperature in Celsius """ - # Calculate resistance at operating temperature (iterative approach) - temp = self.ambient_temp - - # Iterative solution for temperature - for _ in range(10): # Max iterations - # Calculate resistance at current temperature - resistance = self._calculate_resistance(wire_props, temp) - - # Calculate power dissipated - power = current**2 * resistance - - # Calculate heat transfer - heat_transfer = self._calculate_heat_transfer(wire_props, temp) - - # New temperature estimate - new_temp = self.ambient_temp + (power / heat_transfer) - - # Check convergence - if abs(new_temp - temp) < 0.1: - break - - temp = new_temp - - return temp + if not math.isfinite(current) or current < 0: + raise ValueError("Current must be finite and nonnegative") + if current == 0: + return self.ambient_temp + + # Balance electrical input power with convection and radiation losses. + # Bisection avoids oscillation of the previous fixed-point iteration. + def net_heat(temp: float) -> float: + power = current**2 * self._calculate_resistance(wire_props, temp) + heat_loss = self._calculate_heat_transfer(wire_props, temp) * ( + temp - self.ambient_temp + ) + return power - heat_loss + + low = self.ambient_temp + high = max(100.0, self.ambient_temp + 80.0) + while net_heat(high) > 0 and high < 2000.0: + high = min(high * 2, 2000.0) + if net_heat(high) > 0: + raise ValueError("No equilibrium found below 2000ยฐC for this current") + + for _ in range(60): + middle = (low + high) / 2 + if net_heat(middle) > 0: + low = middle + else: + high = middle + return (low + high) / 2 def _calculate_resistance(self, wire_props: WireProperties, temp: float) -> float: """Calculate resistance at given temperature""" @@ -129,7 +142,10 @@ def _calculate_resistance(self, wire_props: WireProperties, temp: float) -> floa alpha = material_props["resistivity_temp_coeff"] # Base resistance at room temperature - base_resistance = wire_props.resistance_per_foot * wire_props.length + length_feet = ( + LengthUnitConverter.to_mm(wire_props.length, wire_props.length_unit) / 304.8 + ) + base_resistance = wire_props.resistance_per_foot * length_feet # Resistance at operating temperature resistance = base_resistance * (1 + alpha * (temp - 20.0)) @@ -246,34 +262,16 @@ def get_wire_properties( # Convert gauge to diameter in mm diameter_mm = WireGaugeConverter.convert_gauge_to_mm(gauge_size, gauge_unit) - # Calculate resistance based on material and diameter - # Use copper as baseline and apply material factor - - # For AWG sizes, use known copper resistance values - if gauge_unit == "AWG" and gauge_size in self.AWG_SPECS: - copper_resistance_per_foot = self.AWG_SPECS[int(gauge_size)][ - "resistance_ohm_per_foot" - ] - else: - # Calculate resistance based on diameter (copper baseline) - # R = ฯ * L/A, where A = ฯ€ * (d/2)ยฒ - # Using copper resistivity as baseline - copper_resistivity_ohm_mm = 1.68e-5 # Ohmยทmm - area_mm2 = math.pi * (diameter_mm / 2) ** 2 - copper_resistance_per_mm = copper_resistivity_ohm_mm / area_mm2 - copper_resistance_per_foot = copper_resistance_per_mm * 304.8 # mm per foot - - # Apply material resistance factor - if material in self.MATERIAL_RESISTANCE_FACTORS: - resistance_factor = self.MATERIAL_RESISTANCE_FACTORS[material] - elif material.lower() in ["kanthal", "fechral"]: - # Handle kanthal variations - resistance_factor = 70.0 - else: + if not math.isfinite(diameter_mm) or diameter_mm <= 0: + raise ValueError("Wire diameter must be finite and positive") + if not math.isfinite(length) or length <= 0: + raise ValueError("Wire length must be finite and positive") + if material not in self.MATERIAL_RESISTIVITY: raise ValueError(f"Unsupported material: {material}") - resistance_per_foot = copper_resistance_per_foot * resistance_factor - resistance_per_meter = resistance_per_foot * 3.28084 # Convert to per meter + area_mm2 = math.pi * (diameter_mm / 2) ** 2 + resistance_per_meter = self.MATERIAL_RESISTIVITY[material] / area_mm2 + resistance_per_foot = resistance_per_meter * 0.3048 return WireProperties( gauge_size=gauge_size, diff --git a/tests/test_cli.py b/tests/test_cli.py index 43388a5..e78e702 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -34,7 +34,8 @@ def test_safety_info_and_warning(command): result = run_cli(command, "--safety-info", "EPS", "250") assert result.returncode == 0, result.stderr assert "Fire risk level: high" in result.stdout - assert "Maximum: 220ยฐC" in result.stdout + assert "Modeled upper bound: 220ยฐC" in result.stdout + assert "Ventilation required: Yes" in result.stdout @pytest.mark.parametrize( diff --git a/tests/test_thermal_equilibrium.py b/tests/test_thermal_equilibrium.py new file mode 100644 index 0000000..bb2f16a --- /dev/null +++ b/tests/test_thermal_equilibrium.py @@ -0,0 +1,79 @@ +"""Check physical invariants of the estimated wire temperature model.""" + +import math + +import pytest + +from wire_temp_calc.wire_temp_calculator import WireTemperatureCalculator + + +@pytest.fixture +def calculator(): + return WireTemperatureCalculator() + + +def test_temperature_increases_with_current(calculator): + wire = calculator.get_wire_properties(22, "AWG", "nichrome", 2, "feet") + currents = (0, 0.1, 1, 2, 5, 10) + temperatures = [ + calculator.calculate_temperature(wire, current) for current in currents + ] + assert temperatures[0] == calculator.ambient_temp + assert all(a < b for a, b in zip(temperatures, temperatures[1:])) + + +@pytest.mark.parametrize("material", ("nichrome", "stainless", "kanthal")) +def test_equivalent_lengths_and_wire_diameters(calculator, material): + settings = ( + (22, "AWG", 2, "feet"), + (22, "AWG", 24, "inch"), + (0.644, "mm", 0.6096, "meters"), + ) + wires = [ + calculator.get_wire_properties(gauge, unit, material, length, length_unit) + for gauge, unit, length, length_unit in settings + ] + for current in (0.5, 1, 3): + baseline = calculator.calculate_temperature(wires[0], current) + assert calculator.calculate_temperature(wires[1], current) == pytest.approx( + baseline + ) + assert calculator.calculate_temperature(wires[2], current) == pytest.approx( + baseline, rel=0.02 + ) + + +def test_equilibrium_balances_electrical_power_and_heat_loss(calculator): + wire = calculator.get_wire_properties(24, "AWG", "kanthal", 0.6, "meters") + temperature = calculator.calculate_temperature(wire, 2) + electrical_power = 4 * calculator._calculate_resistance(wire, temperature) + heat_loss = calculator._calculate_heat_transfer(wire, temperature) * ( + temperature - calculator.ambient_temp + ) + assert electrical_power == pytest.approx(heat_loss, rel=1e-8) + + +@pytest.mark.parametrize( + "material,resistivity", (("nichrome", 1.09), ("kanthal", 1.45)) +) +def test_manufacturer_resistivity_at_room_temperature( + calculator, material, resistivity +): + # Kanthal datasheets give resistivity in ฮฉยทmmยฒ/m; compare R per metre. + wire = calculator.get_wire_properties(1, "mm", material, 1, "meters") + assert wire.resistance_per_meter == pytest.approx(resistivity / (math.pi / 4)) + + +@pytest.mark.parametrize( + "length,diameter", ((0, 0.5), (-1, 0.5), (1, 0), (1, math.nan)) +) +def test_invalid_geometry_rejected(calculator, length, diameter): + with pytest.raises(ValueError): + calculator.get_wire_properties(diameter, "mm", "nichrome", length, "meters") + + +@pytest.mark.parametrize("current", (-1, math.nan, math.inf)) +def test_invalid_currents_rejected(calculator, current): + wire = calculator.get_wire_properties(22, "AWG", "nichrome", 2, "feet") + with pytest.raises(ValueError, match="Current"): + calculator.calculate_temperature(wire, current)