Upload 3 files

README.md

@@ -1,13 +1,238 @@
----
-title: HW3.3
-emoji: ⚡
-colorFrom: pink
-colorTo: blue
-sdk: gradio
-sdk_version: 5.47.2
-app_file: app.py
-pinned: false
-license: mit
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+---
+title: DC Circuit Analysis Calculator
+emoji: ⚡
+colorFrom: blue
+colorTo: green
+sdk: gradio
+sdk_version: 5.47.2
+app_file: app.py
+pinned: false
+license: mit
+short_description: DC circuit analysis calculator with AI explanations
+---
+
+# ⚡ DC Circuit Analysis Calculator
+
+A deterministic, first-principles electrical engineering calculator for series-parallel DC circuit analysis with AI-powered result explanations. This tool performs electrical engineering calculations and provides detailed, human-readable explanations of the mathematical results.
+
+## 🎯 Overview
+
+This calculator solves one of the most fundamental problems in electrical engineering: analyzing a series-parallel DC circuit with resistors. The implementation follows classical circuit theory and provides:
+
+- **Deterministic calculations** based on first principles
+- **Comprehensive validation** of input parameters
+- **Detailed numerical results** with all intermediate calculations
+- **AI-powered explanations** that contextualize the mathematical results
+- **Power analysis** for component safety and efficiency
+- **Professional-grade interface** built with Gradio
+
+## ⚡ Engineering Scope
+
+### Problem Definition
+Analyze a DC circuit with the topology: Voltage Source → R1 (series) → [R2, R3] (parallel) → R4 (series)
+
+### Assumptions
+- DC steady-state conditions
+- Ideal voltage source (no internal resistance)
+- Ideal resistors (no parasitic effects)
+- Linear circuit behavior
+- No temperature effects on resistance
+
+### Input Parameters
+
+#### Voltage Source
+- **Voltage (V):** DC voltage source (0.1-1000 V)
+
+#### Series Resistors
+- **R1 Resistance (Ω):** First series resistor (1-1,000,000 Ω)
+- **R1 Power Rating (W):** Power rating for R1 (0.01-1000 W)
+- **R4 Resistance (Ω):** Second series resistor (1-1,000,000 Ω)
+- **R4 Power Rating (W):** Power rating for R4 (0.01-1000 W)
+
+#### Parallel Resistors
+- **R2 Resistance (Ω):** First parallel resistor (1-1,000,000 Ω)
+- **R2 Power Rating (W):** Power rating for R2 (0.01-1000 W)
+- **R3 Resistance (Ω):** Second parallel resistor (1-1,000,000 Ω)
+- **R3 Power Rating (W):** Power rating for R3 (0.01-1000 W)
+
+### Valid Ranges
+All input parameters include comprehensive validation with engineering-reasonable limits to prevent unrealistic calculations.
+
+## 🧮 Mathematical Foundation
+
+### Equivalent Resistance Calculation
+For the series-parallel circuit:
+
+**Series Resistance:**
+```
+R_series = R1 + R4
+```
+
+**Parallel Resistance:**
+```
+R_parallel = 1 / (1/R2 + 1/R3)
+```
+
+**Total Resistance:**
+```
+R_total = R_series + R_parallel
+```
+
+### Current and Voltage Analysis
+**Total Current:**
+```
+I_total = V_source / R_total
+```
+
+**Series Resistors:**
+- Current: I_total (same for R1 and R4)
+- Voltage drops: V_R1 = I_total × R1, V_R4 = I_total × R4
+
+**Parallel Resistors:**
+- Voltage: V_parallel = I_total × R_parallel
+- Currents: I_R2 = V_parallel / R2, I_R3 = V_parallel / R3
+
+### Power Analysis
+**Power Dissipation:**
+```
+P = V² / R = I² × R = V × I
+```
+
+**Power Balance:**
+```
+P_total = V_source × I_total = P_R1 + P_R2 + P_R3 + P_R4
+```
+
+## 🚀 Usage
+
+### Local Development
+
+1. **Install dependencies:**
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+2. **Run the application:**
+   ```bash
+   python app.py
+   ```
+
+3. **Open in browser:**
+   Navigate to `http://localhost:7860`
+
+### Hugging Face Spaces
+
+The application is deployed as a public Hugging Face Space and can be accessed directly through the web interface.
+
+## 📊 Output Structure
+
+The calculator provides two main outputs:
+
+### 1. Numerical Results Panel
+- Total resistance, current, and power
+- Individual resistor analysis (voltage, current, power)
+- Series and parallel section analysis
+- Power distribution and efficiency
+
+### 2. AI Explanation Panel
+- Human-readable interpretation of results
+- Safety assessment with power rating analysis
+- Engineering recommendations
+- Technical details and methodology notes
+- Design optimization suggestions
+
+## 🔍 Example Calculations
+
+### Basic Circuit (12V, 100Ω+50Ω series, 200Ω||300Ω parallel)
+- **Total Resistance:** 220.0 Ω
+- **Total Current:** 0.055 A
+- **Total Power:** 0.655 W
+- **All Components Safe:** Yes
+
+### High Power Circuit (24V, 50Ω+25Ω series, 100Ω||150Ω parallel)
+- **Total Resistance:** 110.0 Ω
+- **Total Current:** 0.218 A
+- **Total Power:** 5.236 W
+- **All Components Safe:** Yes
+
+### Low Voltage Circuit (3.3V, 220Ω+330Ω series, 470Ω||680Ω parallel)
+- **Total Resistance:** 686.2 Ω
+- **Total Current:** 0.005 A
+- **Total Power:** 0.016 W
+- **All Components Safe:** Yes
+
+## 🛠️ Technical Implementation
+
+### Backend Architecture
+- **`circuit_calculator.py`:** Core calculation engine with deterministic algorithms
+- **`app.py`:** Gradio interface with input validation and result formatting
+- **Structured output:** JSON-based results with comprehensive metadata
+
+### Key Features
+- **Input validation:** Comprehensive range checking and error handling
+- **Modular design:** Separate classes for resistors, circuit configuration, and analysis
+- **Error handling:** Graceful failure with detailed error messages
+- **Extensibility:** Easy to add new circuit topologies or components
+
+### AI Integration
+The explanation system uses a template-based approach that:
+- Analyzes circuit results
+- Provides contextual engineering interpretation
+- Offers design recommendations
+- Explains safety implications
+- Suggests optimization opportunities
+
+## 📚 Educational Value
+
+This calculator serves as an excellent learning tool for:
+- **Engineering students** learning circuit analysis
+- **Practicing engineers** needing quick circuit calculations
+- **Educators** demonstrating Ohm's Law and Kirchhoff's Laws
+- **Anyone** interested in understanding electrical circuits
+
+## ⚠️ Important Disclaimers
+
+1. **Educational Purpose:** This tool is designed for educational and preliminary design purposes only.
+
+2. **Professional Use:** For final circuit design, always consult a licensed electrical engineer.
+
+3. **Limitations:** The calculator assumes:
+   - DC steady-state conditions
+   - Ideal components
+   - Linear behavior
+   - No temperature effects
+
+4. **Validation:** While comprehensive input validation is provided, users should verify results for critical applications.
+
+## 🔧 Development
+
+### Project Structure
+```
+├── app.py                 # Gradio interface
+├── circuit_calculator.py  # Core calculation engine
+├── requirements.txt       # Python dependencies
+└── README.md             # This documentation
+```
+
+### Adding New Features
+The modular design makes it easy to extend:
+- Add new circuit topologies
+- Implement AC analysis
+- Add reactive components (capacitors, inductors)
+- Enhance the explanation system
+
+## 📄 License
+
+This project is open source and available under the MIT License.
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.
+
+## 📞 Support
+
+For questions or support, please open an issue in the project repository.
+
+---
+
+**Built with ❤️ for the engineering community**

circuit_calculator.py

@@ -0,0 +1,331 @@
+"""
+DC Circuit Analysis Calculator
+A deterministic, first-principles electrical engineering calculator for series-parallel resistor circuits.
+"""
+
+import math
+from typing import Dict, Any, List, Tuple
+from dataclasses import dataclass
+
+
+@dataclass
+class Resistor:
+    """Represents a resistor in the circuit"""
+    name: str
+    resistance: float  # Ohms
+    power_rating: float  # Watts (optional)
+    
+    def current_through(self, voltage: float) -> float:
+        """Calculate current through this resistor (Amperes)"""
+        return voltage / self.resistance if self.resistance > 0 else 0
+    
+    def power_dissipated(self, voltage: float) -> float:
+        """Calculate power dissipated by this resistor (Watts)"""
+        return (voltage ** 2) / self.resistance if self.resistance > 0 else 0
+    
+    def voltage_drop(self, current: float) -> float:
+        """Calculate voltage drop across this resistor (Volts)"""
+        return current * self.resistance
+
+
+@dataclass
+class CircuitConfiguration:
+    """Configuration of the circuit topology"""
+    voltage_source: float  # Volts
+    series_resistors: List[Resistor]  # Resistors in series
+    parallel_branches: List[List[Resistor]]  # Each inner list is a parallel branch
+
+
+class DCCircuitAnalyzer:
+    """Deterministic calculator for DC circuit analysis"""
+    
+    def __init__(self, config: CircuitConfiguration):
+        self.config = config
+        self._validate_inputs()
+    
+    def _validate_inputs(self) -> None:
+        """Validate all input parameters are within reasonable ranges"""
+        errors = []
+        
+        # Voltage source validation
+        if self.config.voltage_source <= 0 or self.config.voltage_source > 1000:
+            errors.append("Voltage source must be between 0 and 1000 V")
+        
+        # Series resistors validation
+        for i, resistor in enumerate(self.config.series_resistors):
+            if resistor.resistance <= 0 or resistor.resistance > 1000000:
+                errors.append(f"Series resistor {i+1} resistance must be between 0 and 1,000,000 Ohms")
+            if resistor.power_rating <= 0 or resistor.power_rating > 1000:
+                errors.append(f"Series resistor {i+1} power rating must be between 0 and 1000 Watts")
+        
+        # Parallel branches validation
+        for branch_idx, branch in enumerate(self.config.parallel_branches):
+            if not branch:  # Empty branch
+                errors.append(f"Parallel branch {branch_idx+1} cannot be empty")
+            for resistor_idx, resistor in enumerate(branch):
+                if resistor.resistance <= 0 or resistor.resistance > 1000000:
+                    errors.append(f"Parallel branch {branch_idx+1}, resistor {resistor_idx+1} resistance must be between 0 and 1,000,000 Ohms")
+                if resistor.power_rating <= 0 or resistor.power_rating > 1000:
+                    errors.append(f"Parallel branch {branch_idx+1}, resistor {resistor_idx+1} power rating must be between 0 and 1000 Watts")
+        
+        if errors:
+            raise ValueError("Input validation failed:\n" + "\n".join(errors))
+    
+    def calculate_equivalent_resistance(self) -> float:
+        """Calculate total equivalent resistance of the circuit (Ohms)"""
+        # Calculate series resistance
+        series_resistance = sum(r.resistance for r in self.config.series_resistors)
+        
+        # Calculate parallel branch resistances
+        parallel_resistances = []
+        for branch in self.config.parallel_branches:
+            if branch:  # Non-empty branch
+                branch_resistance = sum(r.resistance for r in branch)
+                parallel_resistances.append(branch_resistance)
+        
+        # Calculate equivalent parallel resistance
+        if parallel_resistances:
+            parallel_equivalent = 1 / sum(1/r for r in parallel_resistances)
+        else:
+            parallel_equivalent = 0
+        
+        # Total equivalent resistance
+        return series_resistance + parallel_equivalent
+    
+    def calculate_total_current(self) -> float:
+        """Calculate total current from voltage source (Amperes)"""
+        total_resistance = self.calculate_equivalent_resistance()
+        return self.config.voltage_source / total_resistance if total_resistance > 0 else 0
+    
+    def calculate_series_analysis(self) -> Dict[str, Any]:
+        """Analyze series resistors"""
+        total_current = self.calculate_total_current()
+        series_analysis = {
+            "total_resistance": sum(r.resistance for r in self.config.series_resistors),
+            "total_current": total_current,
+            "total_power": 0,
+            "resistors": []
+        }
+        
+        for resistor in self.config.series_resistors:
+            voltage_drop = resistor.voltage_drop(total_current)
+            power_dissipated = resistor.power_dissipated(voltage_drop)
+            series_analysis["total_power"] += power_dissipated
+            
+            series_analysis["resistors"].append({
+                "name": resistor.name,
+                "resistance": resistor.resistance,
+                "voltage_drop": voltage_drop,
+                "current": total_current,
+                "power_dissipated": power_dissipated,
+                "power_utilization": (power_dissipated / resistor.power_rating * 100) if resistor.power_rating > 0 else 0
+            })
+        
+        return series_analysis
+    
+    def calculate_parallel_analysis(self) -> Dict[str, Any]:
+        """Analyze parallel branches"""
+        # Calculate voltage across parallel section
+        series_resistance = sum(r.resistance for r in self.config.series_resistors)
+        total_resistance = self.calculate_equivalent_resistance()
+        parallel_resistance = total_resistance - series_resistance
+        
+        total_current = self.calculate_total_current()
+        voltage_across_parallel = total_current * parallel_resistance
+        
+        parallel_analysis = {
+            "voltage_across_parallel": voltage_across_parallel,
+            "branches": []
+        }
+        
+        for branch_idx, branch in enumerate(self.config.parallel_branches):
+            if not branch:
+                continue
+                
+            branch_resistance = sum(r.resistance for r in branch)
+            branch_current = voltage_across_parallel / branch_resistance if branch_resistance > 0 else 0
+            
+            branch_analysis = {
+                "branch_number": branch_idx + 1,
+                "total_resistance": branch_resistance,
+                "current": branch_current,
+                "power": 0,
+                "resistors": []
+            }
+            
+            for resistor in branch:
+                voltage_drop = resistor.voltage_drop(branch_current)
+                power_dissipated = resistor.power_dissipated(voltage_drop)
+                branch_analysis["power"] += power_dissipated
+                
+                branch_analysis["resistors"].append({
+                    "name": resistor.name,
+                    "resistance": resistor.resistance,
+                    "voltage_drop": voltage_drop,
+                    "current": branch_current,
+                    "power_dissipated": power_dissipated,
+                    "power_utilization": (power_dissipated / resistor.power_rating * 100) if resistor.power_rating > 0 else 0
+                })
+            
+            parallel_analysis["branches"].append(branch_analysis)
+        
+        return parallel_analysis
+    
+    def calculate_power_analysis(self) -> Dict[str, Any]:
+        """Calculate total power consumption and efficiency"""
+        total_current = self.calculate_total_current()
+        total_power = self.config.voltage_source * total_current
+        
+        series_analysis = self.calculate_series_analysis()
+        parallel_analysis = self.calculate_parallel_analysis()
+        
+        # Calculate power distribution
+        series_power = series_analysis["total_power"]
+        parallel_power = sum(branch["power"] for branch in parallel_analysis["branches"])
+        
+        return {
+            "total_power_supplied": total_power,
+            "total_power_consumed": series_power + parallel_power,
+            "series_power": series_power,
+            "parallel_power": parallel_power,
+            "efficiency_percent": ((series_power + parallel_power) / total_power * 100) if total_power > 0 else 0,
+            "power_balance_error": abs(total_power - (series_power + parallel_power))
+        }
+    
+    def check_power_ratings(self) -> Dict[str, Any]:
+        """Check if any resistors exceed their power ratings"""
+        warnings = []
+        critical_issues = []
+        
+        # Check series resistors
+        series_analysis = self.calculate_series_analysis()
+        for resistor_data in series_analysis["resistors"]:
+            if resistor_data["power_utilization"] > 100:
+                critical_issues.append(f"Series resistor {resistor_data['name']} exceeds power rating: {resistor_data['power_utilization']:.1f}%")
+            elif resistor_data["power_utilization"] > 80:
+                warnings.append(f"Series resistor {resistor_data['name']} near power limit: {resistor_data['power_utilization']:.1f}%")
+        
+        # Check parallel resistors
+        parallel_analysis = self.calculate_parallel_analysis()
+        for branch in parallel_analysis["branches"]:
+            for resistor_data in branch["resistors"]:
+                if resistor_data["power_utilization"] > 100:
+                    critical_issues.append(f"Parallel resistor {resistor_data['name']} exceeds power rating: {resistor_data['power_utilization']:.1f}%")
+                elif resistor_data["power_utilization"] > 80:
+                    warnings.append(f"Parallel resistor {resistor_data['name']} near power limit: {resistor_data['power_utilization']:.1f}%")
+        
+        return {
+            "warnings": warnings,
+            "critical_issues": critical_issues,
+            "all_safe": len(critical_issues) == 0,
+            "has_warnings": len(warnings) > 0
+        }
+    
+    def perform_analysis(self) -> Dict[str, Any]:
+        """Perform complete circuit analysis and return structured results"""
+        try:
+            # Basic calculations
+            total_resistance = self.calculate_equivalent_resistance()
+            total_current = self.calculate_total_current()
+            
+            # Detailed analysis
+            series_analysis = self.calculate_series_analysis()
+            parallel_analysis = self.calculate_parallel_analysis()
+            power_analysis = self.calculate_power_analysis()
+            safety_check = self.check_power_ratings()
+            
+            # Create structured output
+            results = {
+                "analysis_type": "DC Series-Parallel Circuit Analysis",
+                "status": "success",
+                "circuit_configuration": {
+                    "voltage_source_V": self.config.voltage_source,
+                    "series_resistors": [
+                        {"name": r.name, "resistance_ohms": r.resistance, "power_rating_W": r.power_rating}
+                        for r in self.config.series_resistors
+                    ],
+                    "parallel_branches": [
+                        [
+                            {"name": r.name, "resistance_ohms": r.resistance, "power_rating_W": r.power_rating}
+                            for r in branch
+                        ]
+                        for branch in self.config.parallel_branches
+                    ]
+                },
+                "equivalent_circuit": {
+                    "total_resistance_ohms": total_resistance,
+                    "total_current_A": total_current,
+                    "total_power_W": power_analysis["total_power_supplied"]
+                },
+                "series_analysis": series_analysis,
+                "parallel_analysis": parallel_analysis,
+                "power_analysis": power_analysis,
+                "safety_analysis": safety_check,
+                "validation": {
+                    "circuit_valid": total_resistance > 0,
+                    "power_balance_acceptable": power_analysis["power_balance_error"] < 0.001,
+                    "all_resistors_safe": safety_check["all_safe"]
+                }
+            }
+            
+            return results
+            
+        except Exception as e:
+            return {
+                "analysis_type": "DC Series-Parallel Circuit Analysis",
+                "status": "error",
+                "error_message": str(e),
+                "circuit_configuration": {
+                    "voltage_source_V": self.config.voltage_source,
+                    "series_resistors": [
+                        {"name": r.name, "resistance_ohms": r.resistance, "power_rating_W": r.power_rating}
+                        for r in self.config.series_resistors
+                    ],
+                    "parallel_branches": [
+                        [
+                            {"name": r.name, "resistance_ohms": r.resistance, "power_rating_W": r.power_rating}
+                            for r in branch
+                        ]
+                        for branch in self.config.parallel_branches
+                    ]
+                }
+            }
+
+
+def create_sample_circuit() -> Dict[str, Any]:
+    """Create a sample circuit for testing"""
+    # Create a simple series-parallel circuit
+    # Voltage source -> R1 (series) -> [R2, R3] (parallel) -> R4 (series)
+    
+    series_resistors = [
+        Resistor("R1", 100, 0.25),  # 100 ohms, 0.25W
+        Resistor("R4", 50, 0.5)     # 50 ohms, 0.5W
+    ]
+    
+    parallel_branches = [
+        [Resistor("R2", 200, 0.25)],  # Branch 1: 200 ohms, 0.25W
+        [Resistor("R3", 300, 0.25)]   # Branch 2: 300 ohms, 0.25W
+    ]
+    
+    config = CircuitConfiguration(
+        voltage_source=12.0,  # 12V battery
+        series_resistors=series_resistors,
+        parallel_branches=parallel_branches
+    )
+    
+    analyzer = DCCircuitAnalyzer(config)
+    return analyzer.perform_analysis()
+
+
+if __name__ == "__main__":
+    # Test the calculator
+    results = create_sample_circuit()
+    print("Sample Circuit Analysis Results:")
+    print(f"Status: {results['status']}")
+    if results['status'] == 'success':
+        print(f"Total Resistance: {results['equivalent_circuit']['total_resistance_ohms']:.2f} Ohms")
+        print(f"Total Current: {results['equivalent_circuit']['total_current_A']:.3f} A")
+        print(f"Total Power: {results['equivalent_circuit']['total_power_W']:.3f} W")
+        print(f"All Resistors Safe: {results['validation']['all_resistors_safe']}")
+    else:
+        print(f"Error: {results['error_message']}")

requirements.txt

@@ -0,0 +1,4 @@
+gradio>=5.47.2
+numpy>=1.21.0
+matplotlib>=3.5.0
+pandas>=1.3.0