diff options
Diffstat (limited to '')
| -rw-r--r-- | README.md | 120 |
1 files changed, 120 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..916cb69 --- /dev/null +++ b/README.md @@ -0,0 +1,120 @@ +# Electrotechnique & Electrophysics Sandbox + +Three.js + strict TypeScript + Vite, developed in Ubuntu on WSL2. + +## Develop + +Run in your Ubuntu terminal: + +```bash +cd /home/victor/projects/geekedin +npm install +npm run dev +``` + +Open http://localhost:5173 in your Windows browser. The dev server binds to +127.0.0.1 by default and Vite provides hot module replacement. +Use a browser with WebGL and hardware acceleration enabled. + +Node.js 22.12+ is required; `.nvmrc` selects Node 22 if you use nvm. +For a fresh checkout with a lockfile, use `npm ci` for repeatable installs. + +## Commands + +- `npm run dev`: development server, hot reload. +- `npm run typecheck`: strict TypeScript check. +- `npm test`: physics unit tests with Vitest. +- `npm run test:e2e`: Chromium browser checks with Playwright. +- `npm run build`: type check and production bundle in `dist/`. +- `npm run preview`: preview the production build at http://localhost:4173. + +## Eight experiments from PLAN.md + +Each lesson has an interactive 3D scene, adjustable parameters, live SI +measurements, governing equations, a short explanation, a challenge and a +model/scales disclosure. Use the subject tabs or these URL fragments: + +| Subject | Interactive view | URL fragment | +| --- | --- | --- | +| Electric charge, force and field | Dipole/like charges, field arrows and force on a source | `#field` | +| Electric flux and charge | Move a signed charge through a spherical Gaussian surface | `#flux` | +| Electric potential energy | Vary separation and charge, plot U(r) and field work | `#energy` | +| Electric potential and gradient | Potential landscape with field arrows and a movable probe | `#potential` | +| Capacitance | Vary plate area, gap and applied voltage | `#capacitance` | +| Dielectric materials | Polarization at fixed voltage versus fixed free charge | `#dielectric` | +| Current | Ohmic copper wire with electrons drifting against conventional current | `#current` | +| Semiconducting materials | Intrinsic, n-type and p-type silicon, carrier densities and bands | `#semiconductor` | + +Drag to orbit, scroll to zoom, right-drag to pan. Focus the canvas to pan +with arrow keys. Reset the camera independently or reset the current +experiment. Settings survive switching subjects for the current page session. +URL fragments support browser back/forward and direct links. Animations can +be paused, and start paused when reduced motion is preferred. Without WebGL, +lessons, controls and measurements remain usable. + +These are teaching models: electrostatics in vacuum, ideal parallel plates, +linear fully filling dielectrics, an Ohmic copper wire at fixed temperature, +and non-degenerate silicon in equilibrium at 300 K. The semiconductor lab +uses approximate reference constants disclosed in the lesson. It does not +model a p–n junction or compare real devices. Geometry, arrow lengths, +carrier populations and animation speeds use explicit visual scales. + +In the isolated dielectric experiment, each parameter setting represents +charging the selected geometry in vacuum at the charging voltage, then +disconnecting and filling it with dielectric. Q is fixed while varying κ; +changing geometry or charging voltage prepares a different capacitor state. + +## Verification + +```bash +npm test +npm run build +# Once per development machine: +npx playwright install chromium +npm run test:e2e +``` + +The unit suite checks force direction, the potential gradient, energy, +Gauss's law, capacitance, fixed-Q/fixed-V dielectric behavior, current, +drift and semiconductor mass action/neutrality. Playwright checks rendered +content in all eight scenes, parameter changes, reset, history, mobile layout, +pausing and the WebGL fallback. The browser suite starts Vite if necessary. +On a minimal Ubuntu installation, Playwright may require browser libraries; +its installer can identify them (`npx playwright install-deps chromium`). + +## Extend + +- `src/main.ts`: subject navigation, parameter controls, lesson UI. +- `src/experiments.ts`: lesson definitions, defaults, units and measurements. +- `src/scene/lab.ts`: renderer, orbit controls, resizing and frame loop. +- `src/scene/experiments.ts`: one scene builder per topic. +- `src/scene/primitives.ts`: shared geometry/labels and GPU resource disposal. +- `src/physics/`: framework-independent SI models and unit tests. +- `tests/lab.spec.ts`: real-browser interaction and rendering checks. + +Add model calculations under `src/physics/`, then connect an experiment +and a scene builder. Keep physical quantities in SI and perform display +conversion in the lesson definitions. + +## WSL2 notes + +Keep the project in `/home/victor/projects` for Linux file watching and I/O. +Run Node/npm in Ubuntu rather than mixing Windows and Linux installations. +For VS Code, run `code .` in Ubuntu and use its WSL extension. + +If Windows cannot reach localhost, first check the URL printed by Vite (it +may choose another port if 5173 is busy). If WSL localhost forwarding is +unavailable, run `npm run dev -- --host 0.0.0.0` and access the WSL address +shown by `hostname -I`. This exposes the development server on available +interfaces; use it only on a trusted development network. + +If file changes do not reload on a mounted Windows filesystem, move the +project into the Linux filesystem. Polling can be enabled in Vite config if +needed, but is unnecessary for the default project location. + +## References + +- [Vite getting started](https://vite.dev/guide/) +- [Three.js installation](https://threejs.org/manual/pages/installation.html) +- [OpenStax University Physics Volume 2](https://openstax.org/details/books/university-physics-volume-2) +- [OpenStax band theory of solids](https://openstax.org/books/university-physics-volume-3/pages/9-5-band-theory-of-solids) |