Metadata-Version: 2.4
Name: gearmaster
Version: 0.1.1
Summary: Complete Engineering Analysis Suite for mechanical systems simulation, CAD, FEA, and signal processing
Author-email: Simone Lucertini <simone.lucertini@gmail.com>
License: GPL-3.0-only
Project-URL: Homepage, https://github.com/simoneluce/GearMaster
Project-URL: Documentation, https://gearmaster.readthedocs.io
Project-URL: Repository, https://github.com/simoneluce/GearMaster.git
Project-URL: Issues, https://github.com/simoneluce/GearMaster/issues
Project-URL: Changelog, https://github.com/simoneluce/GearMaster/releases
Keywords: engineering,simulation,CAD,FEA,signal-processing,hydraulic,mechanical,structural-analysis
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Manufacturing
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: scipy>=1.10.0
Requires-Dist: matplotlib>=3.7.0
Requires-Dist: customtkinter>=5.2.0
Requires-Dist: Pillow>=9.5.0
Requires-Dist: plotly>=5.15.0
Requires-Dist: seaborn>=0.13.0
Requires-Dist: mplcursors>=0.5
Requires-Dist: scikit-learn>=1.3.0
Requires-Dist: opencv-python>=4.8.0
Requires-Dist: h5py>=3.8.0
Requires-Dist: openpyxl>=3.1.0
Requires-Dist: ansys-dpf-core>=0.8.0
Requires-Dist: ansys-dpf-post>=0.6.0
Provides-Extra: visual
Requires-Dist: customtkinter>=5.2.0; extra == "visual"
Requires-Dist: Pillow>=9.5.0; extra == "visual"
Provides-Extra: visualization
Requires-Dist: pyvista>=0.42.0; extra == "visualization"
Requires-Dist: vtk>=9.0; extra == "visualization"
Requires-Dist: markdown>=3.4; extra == "visualization"
Provides-Extra: ansys
Requires-Dist: ansys-dpf-core>=0.8.0; extra == "ansys"
Requires-Dist: ansys-dpf-post>=0.6.0; extra == "ansys"
Provides-Extra: data
Requires-Dist: h5py>=3.8.0; extra == "data"
Requires-Dist: openpyxl>=3.1.0; extra == "data"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: pylint>=2.17.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.4.0; extra == "docs"
Requires-Dist: mkdocs-material>=9.0.0; extra == "docs"
Provides-Extra: windows
Requires-Dist: pywin32>=305; sys_platform == "win32" and extra == "windows"
Requires-Dist: winshell>=0.6; sys_platform == "win32" and extra == "windows"
Dynamic: license-file

# GearMaster - Complete Engineering Analysis Suite

[![Python Version](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Status](https://img.shields.io/badge/status-Alpha-orange.svg)](#)

> A comprehensive Python-based engineering platform for mechanical systems simulation, CAD operations, FEA analysis, hydraulic systems modeling, and signal processing. Built with both programmatic and visual programming interfaces.

## 🎯 Overview

**GearMaster** is a professional-grade engineering suite designed for:
- 🔧 **Mechanical Component Analysis** - Fasteners, bearings, gears, shafts
- 🏗️ **Structural Analysis** - FEA with Ansys DPF integration, cross-section properties
- 💧 **Hydraulic Systems Modeling** - Cylinders, motors, valves, manifolds
- 📊 **Signal Processing** - Time-series analysis, FFT, filtering, data analysis
- 🎨 **CAD Operations** - Geometric modeling and manipulation
- 📈 **Data Management** - Multi-format data handling (CSV, Excel, HDF5)

### Core Features

- **Dual Interface Model**
  - **Programmatic**: Direct Python API via `GM_modules` for automation and scripting
  - **Visual**: Node-based visual programming via `GM_Visual` for interactive workflows

- **3D Analysis & Visualization**
  - HEXA8 finite element support
  - Rotation-invariant strain energy calculations
  - Ansys DPF/PyDPF integration for result processing

- **Material Library**
  - Comprehensive material property database
  - Metric and SAE fastener specifications
  - Pre-configured material profiles

- **Extensible Architecture**
  - Modular design with 11 specialized engineering modules
  - Plugin-ready node system for visual programming
  - Clean separation of concerns

---

## 🏗️ Architecture Overview

### `GM_modules` - Core Engineering Libraries

**What it is:** The programmatic foundation of GearMaster. A collection of 11 specialized Python modules providing direct APIs for engineering calculations and operations.

**Use Cases:**
- Automated batch analysis scripts
- Integration with other Python tools/frameworks
- Custom simulation workflows
- CI/CD pipelines and testing

**Available Modules:**

| Module | Purpose | Key Classes/Functions |
|--------|---------|----------------------|
| **Data** | Multi-format data management (CSV, Excel, HDF5, JSON) | DataManager, MultiColumn |
| **Signals** | Time-series processing, FFT, filtering, analysis | TimeSeriesConverter, TimeSeriesGenerator, DfTm, DsTm |
| **Mechanical** | Fastener specs, bearing properties, gear calculations | Fasteners, Bearings, MaterialSpecifications |
| **Structures** | FEA, cross-section properties, structural analysis | FEA Core, Cross-Section Solver, SWA (Strain-based Analysis) |
| **Materials** | Material property database, specifications | MaterialLibrary, PropertyCalculations |
| **Hydraulic** | Hydraulic component modeling | Cylinders, Motors, Valves, Manifolds |
| **Fea** | Finite Element Analysis framework | Mesh utilities, Element definitions, Solvers |
| **Cad** | CAD geometry operations | Geometric primitives, Boolean operations |
| **pyAnsys** | Ansys/PyDPF integration | DPF Core, DPF Post-processing, Result parsing |
| **Meshless** | Meshless numerical methods | Meshless algorithms, Geometry utilities |
| **GUIs** | Reusable GUI components | Custom widgets, dialog templates |

**Example Usage:**

```python
from GM_modules.Signals import TimeSeriesGenerator, DfTm
from GM_modules.Data import DataManager
from GM_modules.Structures import FEA

# Create time series data
gen = TimeSeriesGenerator()
signal = gen.create_sine_wave(frequency=50, amplitude=1.0, duration=10)

# Manage data
dm = DataManager()
dm.import_data(signal)

# Analyze structure
fea = FEA()
results = fea.analyze_beam(length=1.0, load=1000)
```

---

### `GM_Visual` - Node-Based Visual Programming System

**What it is:** An interactive visual programming interface built on `GM_modules`. Use drag-and-drop nodes to create complex engineering workflows without writing code.

**Use Cases:**
- Interactive analysis and exploration
- Non-programmer engineers creating workflows
- Educational demonstrations
- Rapid prototyping of analysis pipelines

**Key Features:**
- **Node Canvas**: Drag-and-drop node-based programming
- **Node Library**: Pre-built nodes for all GM_modules functions
- **Project Management**: Save/load workflows as `.gmvproj` files
- **Live Execution**: Execute workflows with real-time result visualization
- **CustomTkinter UI**: Modern, responsive interface
- **Debug Terminal**: In-app logging and error tracking

**Node Categories:**
- Data Input/Output nodes
- Signal Processing nodes
- FEA/Structural Analysis nodes
- Mechanical Component nodes
- Material Property nodes
- Hydraulic System nodes
- Visualization nodes
- Custom nodes (extensible)

**Example Workflow:**
```
[CSV Loader] → [Time-Series Generator] → [FFT Analysis] → [Plot Results]
```

**Launch:**
```bash
python -m GM_Visual.main
# or
python GM_Visual/main.py
```

---

## 📦 Installation

### From PyPI (When Published)

```bash
# Core installation
pip install gearmaster

# With Ansys DPF support
pip install gearmaster[ansys]

# With visual programming interface
pip install gearmaster[visual]

# Complete installation
pip install gearmaster[visual,ansys,data]
```

### From Source (Development)

```bash
git clone https://github.com/simoneluce/GearMaster.git
cd GearMaster

# Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode with all features
pip install -e ".[visual,ansys,data,dev]"
```

### Requirements

- **Python**: 3.9 or higher
- **Core Dependencies**: NumPy, Pandas, SciPy, Matplotlib
- **Optional**: Ansys DPF (for `pyAnsys` and `Structures` modules)

---

## 🚀 Quick Start

### Using GM_modules (Programmatic)

```python
# Import a module
from GM_modules.Signals import TimeSeriesGenerator, DfTm
from GM_modules.Materials import MaterialLibrary

# Create engineering objects
time_gen = TimeSeriesGenerator()
mat_lib = MaterialLibrary()

# Access functionality
signal = time_gen.create_sine_wave(freq=10, duration=5)
steel = mat_lib.get_material("Steel_AISI_1045")

print(f"Signal length: {len(signal)}")
print(f"Steel yield: {steel.yield_strength} MPa")
```

### Using GM_Visual (Interactive)

```bash
# Start the visual programming interface
python -m GM_Visual.main

# Then in the GUI:
# 1. Create New Project
# 2. Drag nodes from right panel to canvas
# 3. Connect nodes by dragging pins
# 4. Click Run → Run All to execute workflow
# 5. View results in execution terminal
```

---

## 📚 Project Structure

```
GearMaster/
├── GM_modules/              # Core engineering libraries
│   ├── Signals/            # Signal processing & time-series
│   ├── Structures/         # FEA and structural analysis
│   ├── Mechanical/         # Mechanical components
│   ├── Materials/          # Material properties
│   ├── Hydraulic/          # Hydraulic systems
│   ├── Data/               # Data management
│   ├── Cad/                # CAD operations
│   ├── Fea/                # FEA framework
│   ├── pyAnsys/            # Ansys DPF integration
│   ├── Meshless/           # Meshless methods
│   └── GUIs/               # GUI components
│
├── GM_Visual/               # Visual programming system
│   ├── src/                # Source code
│   │   ├── nodes/          # Node definitions
│   │   ├── canvas/         # Canvas implementation
│   │   ├── core/           # Core systems
│   │   └── ...
│   ├── tests/              # Test suite
│   ├── main.py             # Application entry point
│   └── requirements.txt     # Visual-specific deps
│
├── docs/                    # Documentation (mkdocs)
├── tests/                   # Integration tests
├── pyproject.toml           # Python packaging config
├── requirements.txt         # All dependencies
└── README.md                # This file
```

---

## 🔄 Differences: GM_modules vs GM_Visual

| Aspect | **GM_modules** | **GM_Visual** |
|--------|---|---|
| **Interface** | Python API (programmatic) | GUI (node-based) |
| **Usage** | Code-driven automation | Drag-and-drop workflows |
| **Target User** | Programmers, Engineers, Researchers | Engineers, Analysts |
| **Extensibility** | Easy - add Python functions | Moderate - create custom nodes |
| **Performance** | Native Python speed | Slight overhead from GUI |
| **Dependency Stack** | Lightweight core | Requires CustomTkinter |
| **Data Flow** | Direct function calls | Visual connections (pins) |
| **Debugging** | Python debuggers, logging | Built-in terminal, node debugging |
| **Version Lock** | Version 0.102.1 | Version 0.7.7 |
| **Learning Curve** | Python knowledge required | Visual intuition required |

### When to Use What

**Choose GM_modules when:**
- ✅ Automating repetitive analysis tasks
- ✅ Integrating with other Python libraries
- ✅ Building production pipelines
- ✅ Requiring maximum performance
- ✅ You're comfortable with Python

**Choose GM_Visual when:**
- ✅ Exploring data interactively
- ✅ Prototyping workflows quickly
- ✅ Team includes non-programmers
- ✅ Teaching engineering concepts
- ✅ Need visual feedback on workflows

---

## 🧪 Testing

```bash
# Run all tests
pytest

# Run tests for specific module
pytest tests/ GM_modules/Signals/tests/

# With coverage report
pytest --cov=GM_modules --cov-report=html
```

Tests follow pytest conventions with `test_*.py` files.

---

## 📖 Documentation

Full documentation available via MkDocs:

```bash
# Install docs dependencies
pip install gearmaster[docs]

# Serve documentation locally
mkdocs serve

# Build static docs
mkdocs build
```

Visit [docs/](docs/) for detailed module documentation, tutorials, and API reference.

---

## 🤝 Contributing

We welcome contributions! Before starting work on a new module:

> **⚠️ Please contact the owner before starting a new module or making major changes.**

1. Create a feature branch from `develop`
2. Implement your changes following the repository style
3. Add tests in the appropriate `tests/` folder
4. Update documentation in the corresponding `docs/` folder
5. Submit a pull request against `develop` branch

**Coding Standards:**
- Python 3.9+ compatible
- Use type hints where possible
- Follow PEP 8 style guide
- Document all public APIs
- Include unit tests (pytest)

---

## 📋 Module Development Guide

Each module follows a standard structure:

```
ModuleName/
├── __init__.py              # Module exports
├── core.py                  # Main functionality
├── [other core files].py    
├── tests/                   # pytest test files
│   └── test_*.py
├── docs/                    # Module documentation
│   └── [module].md
└── version.py               # Version info
```

---

## 📝 License

MIT License - See [LICENSE](LICENSE) file for details.

---

## 👤 Author

**Simone Lucertini**
- Repository: [github.com/simoneluce/GearMaster](https://github.com/simoneluce/GearMaster)

---

## ⚠️ Status

**Current Version**: 0.102.1  
**Status**: Alpha (under active development)

This project is actively maintained. Features and APIs may change. For production use, pin to a specific version.

---

## 🔗 Related Projects

- **machinesim**: Machine simulation framework
- **telematics**: Telemetry and data logging system

---

## 📞 Support

- 📧 Create an issue on GitHub for bug reports
- 💬 Discussions for feature requests
- 📖 Check documentation in `docs/` folder

---

**Happy analyzing! 🚀**
