feat(wind-farm): add the wind farm explainer

explainers/wind-farm/explainer.json

@@ -0,0 +1,12 @@
+{
+  "slug": "wind-farm",
+  "tags": ["energy", "mechanics", "weather"],
+  "cover": "cover.webp",
+  "entry": "src/index.ts",
+  "chapters": "chapters.html",
+  "locales": ["en", "zh", "es", "uk", "pt", "fr", "de", "ja"],
+  "social": {
+    "image": "social/og-image.png",
+    "alt": "A wind farm on rolling land with one turbine close up, beside the title How a wind farm works"
+  }
+}

explainers/wind-farm/src/ids.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest';
+import {
+  FARM_PART_IDS,
+  FOLLOW_DAY,
+  PART_IDS,
+  PRESET_IDS,
+  PRESET_SCENES,
+  SCENE_IDS,
+  SCENE_PARTS,
+  SPACING_CHOICE_IDS,
+  SPACING_OPTIONS,
+  TURBINE_PART_IDS,
+  WIND_AT_IDS,
+  WIND_PRESET_IDS,
+} from './ids';
+
+describe('ids', () => {
+  it('names every part once', () => {
+    expect(PART_IDS).toHaveLength(TURBINE_PART_IDS.length + FARM_PART_IDS.length);
+    expect(new Set(PART_IDS).size).toBe(PART_IDS.length);
+  });
+
+  it('splits the parts between the two scenes with no overlap', () => {
+    expect(Object.keys(SCENE_PARTS).sort()).toEqual([...SCENE_IDS].sort());
+    const scenePartIds = SCENE_IDS.flatMap((scene) => [...SCENE_PARTS[scene]]);
+    expect(scenePartIds).toHaveLength(PART_IDS.length);
+    expect(new Set(scenePartIds)).toEqual(new Set(PART_IDS));
+  });
+
+  it('places every preset in a scene', () => {
+    expect(Object.keys(PRESET_SCENES)).toEqual([...PRESET_IDS]);
+    PRESET_IDS.forEach((preset) => {
+      expect(SCENE_IDS).toContain(PRESET_SCENES[preset]);
+    });
+  });
+
+  it('offers following the day before the wind presets', () => {
+    expect(WIND_AT_IDS[0]).toBe('day');
+    expect(WIND_AT_IDS).toEqual([FOLLOW_DAY, ...WIND_PRESET_IDS]);
+  });
+
+  it('labels each spacing choice with its rotor diameters', () => {
+    expect(SPACING_CHOICE_IDS).toEqual(SPACING_OPTIONS.map(String));
+  });
+});

explainers/wind-farm/src/ids.ts

@@ -0,0 +1,176 @@
+export const SCENE_IDS = ['farm', 'turbine'] as const;
+
+export type SceneId = (typeof SCENE_IDS)[number];
+
+export const TURBINE_PART_IDS = [
+  'land',
+  'foundation',
+  'tower',
+  'transformer',
+  'towerCable',
+  'nacelle',
+  'cooler',
+  'bedplate',
+  'hub',
+  'blades',
+  'pitchCylinders',
+  'mainBearing',
+  'mainShaft',
+  'gearbox',
+  'brakeDisc',
+  'generator',
+  'converter',
+  'yawDrives',
+  'sweptArea',
+  'streamlinesGroup',
+  'heroWake',
+] as const;
+
+export const FARM_PART_IDS = [
+  'farmLand',
+  'farmTurbines',
+  'accessRoads',
+  'spacingMarker',
+  'prevailingWind',
+  'windArrows',
+  'shearProfile',
+  'wakePlumes',
+  'collectorCables',
+  'substation',
+  'gridLine',
+] as const;
+
+export const PART_IDS = [...TURBINE_PART_IDS, ...FARM_PART_IDS] as const;
+
+export type PartId = (typeof PART_IDS)[number];
+
+export const SCENE_PARTS: Readonly<Record<SceneId, readonly PartId[]>> = {
+  turbine: TURBINE_PART_IDS,
+  farm: FARM_PART_IDS,
+};
+
+export const PHASE_IDS = ['night', 'morning', 'afternoon', 'storm', 'evening'] as const;
+
+export type PhaseId = (typeof PHASE_IDS)[number];
+
+export const PRESET_IDS = ['farm', 'tower', 'nacelle', 'curve', 'wakes', 'grid'] as const;
+
+export type PresetId = (typeof PRESET_IDS)[number];
+
+export const PRESET_SCENES: Readonly<Record<PresetId, SceneId>> = {
+  farm: 'farm',
+  tower: 'turbine',
+  nacelle: 'turbine',
+  curve: 'turbine',
+  wakes: 'farm',
+  grid: 'farm',
+};
+
+export const SITE_WIND_IDS = ['calm', 'typical', 'windy'] as const;
+
+export type SiteWindId = (typeof SITE_WIND_IDS)[number];
+
+export const SPACING_OPTIONS = [5, 7, 9] as const;
+
+export type SpacingD = (typeof SPACING_OPTIONS)[number];
+
+export const SPACING_CHOICE_IDS = ['5', '7', '9'] as const;
+
+export type SpacingChoiceId = (typeof SPACING_CHOICE_IDS)[number];
+
+export const OPERATING_STATE_IDS = [
+  'idle',
+  'partial',
+  'full',
+  'rampDown',
+  'stopping',
+  'parked',
+  'starting',
+] as const;
+
+export type OperatingStateId = (typeof OPERATING_STATE_IDS)[number];
+
+export const NACELLE_CHOICE_IDS = ['closed', 'open'] as const;
+
+export type NacelleChoiceId = (typeof NACELLE_CHOICE_IDS)[number];
+
+export const WIND_PRESET_IDS = ['cutIn', 'peak', 'rated', 'rampDown', 'cutOut'] as const;
+
+export type WindPresetId = (typeof WIND_PRESET_IDS)[number];
+
+export const FOLLOW_DAY = 'day';
+
+export const WIND_AT_IDS = [FOLLOW_DAY, ...WIND_PRESET_IDS] as const;
+
+export type WindAtId = (typeof WIND_AT_IDS)[number];
+
+export const CHOICE_IDS = ['siteWind'] as const;
+
+export type ChoiceId = (typeof CHOICE_IDS)[number];
+
+export const CHAPTER_ACTION_IDS = ['siteWind', 'spacing', 'nacelle', 'windAt'] as const;
+
+export type ChapterActionId = (typeof CHAPTER_ACTION_IDS)[number];
+
+export const VIEW_IDS = ['streamlines', 'wakes', 'cables', 'labels', 'cutaway'] as const;
+
+export type ViewId = (typeof VIEW_IDS)[number];
+
+export type ViewOptions = Record<ViewId, boolean>;
+
+export type CameraView =
+  | 'farmAerial'
+  | 'turbineTall'
+  | 'nacelleCutaway'
+  | 'rotorQuarter'
+  | 'wakeStreaks'
+  | 'gridSubstation';
+
+export type RegionId = 'farm' | 'wakes' | 'grid' | 'turbine' | 'nacelle' | 'rotor';
+
+export type AnchorId = 'hub' | 'yawPivot' | 'towerBase' | 'farmCentre' | 'heroSite' | 'substation';
+
+export type Point = readonly [x: number, y: number, z: number];
+
+export type RowIndex = 0 | 1 | 2;
+
+export interface FarmSite {
+  row: RowIndex;
+  column: number;
+  x: number;
+  z: number;
+}
+
+export interface WindReading {
+  speed: number;
+  fromDeg: number;
+  induction: number;
+}
+
+export interface RotorReading {
+  rpm: number;
+  pitchDeg: number;
+  yawDeg: number;
+  state: OperatingStateId;
+  braked: boolean;
+  powerShare: number;
+}
+
+export interface FarmReading {
+  spacing: SpacingD;
+  sites: readonly FarmSite[];
+  deficits: readonly number[];
+  plumeLengthD: number;
+  plumeStrength: number;
+  outputShare: number;
+}
+
+export interface AssemblyState {
+  scene: SceneId;
+  phase: number;
+  playing: boolean;
+  wind: WindReading;
+  rotor: RotorReading;
+  farm: FarmReading;
+  view: ViewOptions;
+}

explainers/wind-farm/src/index.ts

@@ -0,0 +1,28 @@
+import './style.css';
+import { defineExplainer } from '@core/explainer';
+import { SCENE_OPTIONS, mountWindFarmScene } from './scene';
+import { PART_INFO } from './scene/partInfo';
+import { PRESETS, createWindFarmStore } from './state';
+import type { WindFarmStoreState } from './state';
+import { WIND_FARM_TIMELINE } from './timeline';
+import {
+  CHAPTER_ACTIONS,
+  VIEW_TOGGLES,
+  WIND_FARM_CHOICES,
+  WIND_FARM_READOUTS,
+  mountWindFarmUi,
+} from './ui';
+
+export default defineExplainer<WindFarmStoreState>({
+  id: 'wind-farm',
+  timeline: WIND_FARM_TIMELINE,
+  presets: PRESETS,
+  parts: PART_INFO,
+  createStore: () => createWindFarmStore(),
+  dock: { choices: WIND_FARM_CHOICES, toggles: VIEW_TOGGLES },
+  readouts: WIND_FARM_READOUTS,
+  actions: CHAPTER_ACTIONS,
+  scene: SCENE_OPTIONS,
+  mountScene: mountWindFarmScene,
+  mountUi: mountWindFarmUi,
+});

explainers/wind-farm/src/model/constants.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest';
+import {
+  BETZ_LIMIT,
+  CUT_IN_MS,
+  CUT_OUT_MS,
+  FARM_RATED_KW,
+  RAMP_START_MS,
+  RATED_WIND_MS,
+  RESTART_MS,
+  ROTOR_RADIUS_M,
+  TIP_HEIGHT_M,
+  TURBINE_COUNT,
+} from './constants';
+
+describe('constants', () => {
+  it('puts the blade tip 180 m above the ground', () => {
+    expect(ROTOR_RADIUS_M).toBe(75);
+    expect(TIP_HEIGHT_M).toBe(180);
+  });
+
+  it('rates the 27 turbine farm at 113,400 kW', () => {
+    expect(TURBINE_COUNT).toBe(27);
+    expect(FARM_RATED_KW).toBe(113_400);
+  });
+
+  it('caps the share of wind power at the Betz limit of 0.593', () => {
+    expect(BETZ_LIMIT).toBeCloseTo(0.593, 3);
+  });
+
+  it('orders the wind thresholds from cut-in to cut-out', () => {
+    expect(CUT_IN_MS).toBeLessThan(RATED_WIND_MS);
+    expect(RATED_WIND_MS).toBeLessThan(RAMP_START_MS);
+    expect(RAMP_START_MS).toBeLessThan(RESTART_MS);
+    expect(RESTART_MS).toBeLessThan(CUT_OUT_MS);
+  });
+});

explainers/wind-farm/src/model/constants.ts

@@ -0,0 +1,48 @@
+export const ROTOR_DIAMETER_M = 150;
+export const ROTOR_RADIUS_M = ROTOR_DIAMETER_M / 2;
+export const HUB_HEIGHT_M = 105;
+export const TIP_HEIGHT_M = HUB_HEIGHT_M + ROTOR_RADIUS_M;
+export const BLADE_LENGTH_M = 73.7;
+export const MAX_CHORD_M = 4.2;
+export const SWEPT_AREA_M2 = 17_671;
+export const AIR_DENSITY = 1.225;
+
+export const RATED_KW = 4200;
+export const CUT_IN_MS = 3;
+export const RATED_WIND_MS = 12;
+export const RAMP_START_MS = 20;
+export const CUT_OUT_MS = 24.5;
+export const RESTART_MS = 22.5;
+export const MAX_RPM = 10.4;
+export const GEAR_RATIO = 143;
+export const MODEL_TIP_SPEED_RATIO = 8;
+export const FEATHER_DEG = 90;
+export const STOP_MINUTES = 20;
+export const START_MINUTES = 20;
+export const BETZ_LIMIT = 16 / 27;
+
+export const TURBINE_COUNT = 27;
+export const FARM_RATED_KW = TURBINE_COUNT * RATED_KW;
+export const ACROSS_SPACING_D = 4;
+export const DEFAULT_SPACING_D = 7;
+export const WAKE_DECAY = 0.075;
+export const PLUME_VISIBLE_DEFICIT = 0.03;
+export const MAX_PLUME_D = 20;
+export const SHEAR_EXPONENT = 1 / 7;
+
+export const GENERATOR_VOLTS = 800;
+export const COLLECTOR_KV = 36;
+export const GRID_KV = 110;
+
+export const HOME_KWH_PER_YEAR = 10_791;
+export const HOURS_PER_YEAR = 8760;
+export const ANNUAL_MWH_PER_TURBINE = 14_692;
+export const CARBON_G_PER_KWH = 7.3;
+export const PAYBACK_MONTHS = 7.6;
+export const DESIGN_LIFE_YEARS = 20;
+export const BUILT_HA_PER_MW = 0.3;
+export const PROJECT_HA_PER_MW = 34;
+export const FOOTBALL_PITCH_M2 = 7140;
+
+export const WIND_FROM_DEG = 270;
+export const VEER_DEG = 3;