Piiri — Interactive Circuit Analysis Learning Platform & Simulator

Overview

Piiri (“Circuit” in Finnish) is an interactive circuit analysis learning platform and real-time laboratory simulator designed to teach foundational electrical engineering concepts step by step. Built as a lightweight, zero-dependency static web application, it bridges intuitive physical reasoning with formal mathematical circuit analysis.

The curriculum spans 6 core modules and 24 interactive lessons:

1. Foundations, Power & Sources: Current, Ohm’s law, series/parallel networks, passive sign convention ($p(t) = u(t)i(t)$), and independent vs. dependent sources ($i = g_m u_x$).
2. DC Network Analysis & Transformations: Voltage/current dividers under load, Y–$\Delta$ transformations, Nodal Analysis (KCL), Mesh Current Analysis (KVL), Superposition, and Thévenin/Norton equivalents.
3. Energy Storage & First-Order Transients: Capacitors ($q = Cu$, $i = C \frac{du}{dt}$), inductors ($u = L \frac{di}{dt}$), stored energy, and step-response time constants ($\tau = RC$, $\tau = L/R$).
4. Sinusoidal Steady-State (AC) & Frequency Response: Complex phasors, RLC impedance, passive RC/RL filters, Bode magnitude/phase intuition, and resonance.
5. Complex Power & Impedance Matching: Active ($P$), reactive ($Q$), and apparent power ($S = P + jQ$), power factor correction, and maximum power transfer ($Z_L = Z_{\text{Th}}^*$).
6. Engineering Applications: Ideal transformers, operational amplifier (op-amp) feedback topologies, and balanced three-phase ($\text{Y}/\Delta$) systems.

---

System Architecture & Design

1. Pedagogical Flow & State Architecture

Every lesson follows a structured multi-stage learning loop:

• Conceptual Foundation first: Before exposing formulas or numeric sliders, learners complete a qualitative thought experiment (“Pieni ajatuskoe”) to build physical intuition.
• Interactive Circuit Laboratory: A deterministic real-time solver recomputes branch currents, node voltages, phasor angles, and power balances on every parameter change, updating a custom vector schematic (<svg viewBox="0 0 600 300">) and animated charge-flow paths.
• Practice & Seeded Mastery Exams: Includes 67 guided practice questions with targeted misconception feedback, plus a seeded procedural assessment generator (assessment.js) that synthesizes randomized numerical exam pairs for mastery verification.

2. Mathematical Circuit Models

All 24 laboratory modules evaluate exact analytical circuit equations in SI units. For example:

• Two-Loop Mesh Analysis & Y–$\Delta$ Equivalent Networks:

  $$\begin{bmatrix} R_1 + R_m & -R_m \\ -R_m & R_2 + R_m \end{bmatrix} \begin{bmatrix} i_1 \\ i_2 \end{bmatrix} = \begin{bmatrix} U \\ 0 \end{bmatrix}, \qquad R_A = \frac{R_{AB} R_{CA}}{R_{AB} + R_{BC} + R_{CA}}$$

• First-Order RC/RL Transient Step Response & Stored Energy:

  $$u_C(t) = U \left( 1 - e^{-t / \tau} \right), \quad W_C = \frac{1}{2} C u_C^2, \qquad i_L(t) = \frac{U}{R} \left( 1 - e^{-t / \tau} \right), \quad W_L = \frac{1}{2} L i_L^2$$

• Sinusoidal AC Impedance & Phasor Domain:

  $$Z(\omega) = R + j\left( \omega L - \frac{1}{\omega C} \right) = |Z| e^{j\theta}, \qquad \bar{I} = \frac{\bar{U}}{Z(\omega)} = \frac{U_{\text{rms}}}{\sqrt{R^2 + (X_L - X_C)^2}} \angle -\arctan\left(\frac{X_L - X_C}{R}\right)$$

3. Deterministic Laboratory Engine & Verification Suite

The simulation engine (labs.js) pairs each circuit solver with a procedural SVG schematic generator (element, source, wave, arrow) with zero external runtime dependencies:

// Excerpt from Piiri's AC Series RLC Impedance Laboratory (labs.js)
labs.impedance = {
  defaults: { mode: 'rl', u: 10, r: 10, l: 10, c: 100, omega: 500 },
  compute: (p) => {
    const xl = p.omega * p.l * 0.001;
    const xc = 1 / (p.omega * p.c * 1e-6);
    const x = p.mode === 'rl' ? xl : p.mode === 'rc' ? -xc : xl - xc;
    const z = Math.hypot(p.r, x);
    const phase = -Math.atan2(x, p.r);
    return {
      xl,
      xc,
      x,
      z,
      i: p.u / z,
      phaseDeg: (phase * 180) / Math.PI,
      ire: (p.u * p.r) / z ** 2,
      iim: (-p.u * x) / z ** 2,
    };
  },
};

To guarantee physical and numerical accuracy across all lessons, a headless Node.js verification harness (verify.cjs) executes the entire application inside a node:vm sandbox—asserting KCL/KVL invariants, energy conservation, phasor phase relationships, and localStorage state migrations (v1 $\to$ v2) across hundreds of test cases.

---

Results & Takeaways

• Zero-Dependency Performance: The complete 24-lesson platform, SVG schematic renderer, and interactive kaavapaperi (formula scratchpad) load instantaneously as pure static assets without heavy framework bundles.
• Automated Physical Invariant Testing: Using verify.cjs to test KCL ($\sum I = 0$), KVL ($\sum U = 0$), passive sign power balance ($\sum P = 0$), and SVG output validity (NaN/Infinity guards) caught edge-case division-by-zero and phase-wrapping bugs early.
• Gamified Progression Without Gating Content: Learners earn points for completing lessons (+20 pts) and unassisted mastery challenges (+10 bonus pts) to unlock custom hardware-inspired UI themes (Copper PCB, Oscilloscope, and Night) while keeping all educational material freely accessible from the start.