PowerLab: Deterministic Clean Energy Planning & Modeling Platform

PowerLab (powelab.org) is an open-source, deterministic computational modeling platform designed to unify clean energy planning across:

$$\text{Home Energy} \longleftrightarrow \text{Battery Storage} \longleftrightarrow \text{Solar Photovoltaics} \longleftrightarrow \text{Electric Vehicles}$$

Unlike commercial aggregators that rely on opaque heuristic estimates or lead-generation funnels, PowerLab provides open mathematical models, transparent loss derivations, and standards-compliant engineering formulas with zero database tracking.

---

⚡ Key Architectural Pillars

• Pure Deterministic Engines: Every calculation engine in src/lib/calculators/ is written in pure TypeScript with zero external dependencies, deterministic test suites, and transparent formulas.
• Physical Loss Mechanisms Included: Models dynamic depth of discharge (DoD), Peukert capacity derating ($I^k \cdot t = C$), inverter standby tare draw ($15\text{W}\text{--}30\text{W}$ continuous), locked rotor inrush amperage (LRA), and cold-temperature open-circuit voltage ($V_{oc}$) expansion.
• Privacy by Design: Zero database, zero authentication, zero user tracking, and no cookies. User energy profiles and multi-tool scenarios persist strictly within local browser localStorage.
• Governing Standards: Formulations adhere to IEEE Std 485, National Electrical Code (NEC / NFPA 70 Articles 625, 690, 702, and 706), NREL PVWatts V8 algorithms, and ASHRAE climatic design conditions.
• Direct Academic & Educational Alignment: Officially mapped as open courseware on OER Commons for university engineering programs, CTE electrical apprenticeships, and physics classrooms.

---

📊 Calculator & Modeling Suites

Domain	Key Interactive Tools & Models
🔋 Battery Storage	• Battery Runtime Calculator (Peukert + Inverter Tare) • Battery Size Calculator • Battery Capacity Calculator • Battery Charging Time Calculator • UPS Runtime & UPS Battery Sizing • Home Battery Size Calculator • Portable Power Station Calculator
☀️ Solar Photovoltaics	• Solar Panel Tilt Calculator (PVWatts V8 + Latitude Cosine Angle) • Solar Panel Output Calculator • Solar Panel Size Calculator • Solar Load Calculator • Solar Battery Bank Sizing • MPPT Solar Charge Controller Calculator • Solar System Payback & ROI
⚡ Home Energy & Loads	• Electricity Usage Calculator • Energy Bill Calculator • Appliance Wattage & Duty Cycle • Generator Sizing Calculator (Motor Inrush & Starting kVA) • Air Conditioner Operating Cost Calculator (SEER2 Derating) • Heat Pump Cost & COP Calculator • Space Heater Electricity Cost Calculator
🚗 Electric Vehicles	• EV Charging Time Calculator (Level 1, Level 2, DC Fast) • EV Charging Cost Calculator • EV Range Calculator (Aerodynamic Drag & HVAC Auxiliary Loads) • EV Fuel Savings Calculator • EV Charger Dedicated Breaker Sizing (NEC 625 125% Rule) • Vehicle-to-Load (V2L) Runtime Calculator

---

🛠️ Tech Stack & Source Layout

• Framework: Next.js 15 (App Router, React 19, Server-Rendered SEO/GEO content)
• Language: TypeScript 5.9 (Strict Type Checking, 0 any)
• Styling: Modular CSS & Custom Design System (Fluid Typography, Dark/Light palettes, Semantic HTML5)
• Testing: Vitest 3.2 (Unit tests, edge-case bounds, invariant tests, handoff integration suites)
• Deployment: Vercel Automated Edge Integration

src/
├── app/                  # Next.js App Router (Calculators, Guides, APIs)
│   ├── battery/          # Battery storage planning routes
│   ├── solar/            # Solar PV calculation routes
│   ├── home-energy/      # Residential load and appliance routes
│   ├── ev/               # Electric vehicle energy and charging routes
│   ├── guides/           # Technical educational reference guides
│   └── api/              # Proxy endpoints (PVWatts V8, IndexNow)
├── components/           # Accessible, mobile-first design system
│   ├── calculator/       # Calculator shells, formula cards, assumption trays
│   ├── inputs/           # Accessible numeric and slider controls
│   └── seo/              # LaTeX drawers, JSON-LD schema, citations
├── data/                 # Deterministic static datasets (ASHRAE, NREL, appliances)
├── lib/
│   ├── calculators/      # PURE DETERMINISTIC ENGINES (Isolated from UI/DOM)
│   ├── energy-profile/   # LocalStorage cross-calculator state sync
│   ├── providers/        # External model adapters (NREL PVWatts)
│   └── seo/              # Structured data generators and canonical metadata
└── types/                # Shared domain schemas and calculation envelopes

---

🚀 Getting Started

Prerequisites

• Node.js 18.17+ or 20+
• npm, pnpm, or yarn

Installation & Local Development

1. Clone the repository:

   git clone https://github.com/miadsaadidi/powerlab.git
   cd powerlab

2. Install dependencies:

   npm install

3. Run the local development server:

   npm run dev
   # Or with Turbopack acceleration:
   npm run dev:all

   Open http://localhost:3000 with your browser.

4. Run the test suite:

   npm test

5. Typecheck verification:

   npm run typecheck

---

🔬 Peer Review & Academic Contribution

We welcome contributions from electrical engineers, researchers, solar installers, and educators. Whether auditing engine equations against published IEEE/IEC literature, providing real-world battery discharge curves, or introducing classroom lab modules:

• Please review CONTRIBUTING.md for our branch lifecycle and PR review rules.
• Participate in ongoing modeling discussions on GitHub Discussions.
• Open an Issue if you discover an unhandled physical loss factor or edge-case discrepancy.

---

📄 License

This project is licensed under the MIT License. Calculators, formulas, and educational guides are maintained for open research and public benefit.