e.target.style.background = "#f0f0f0"}
+ onMouseLeave={e => e.target.style.background = "transparent"}
+ onClick={handleSolar}
+ >
+ Calculate Solar Performance
+
e.target.style.background = "#f0f0f0"}
diff --git a/app/src/components/MapViewer.test.js b/app/src/components/MapViewer.test.js
new file mode 100644
index 00000000..2afce0f4
--- /dev/null
+++ b/app/src/components/MapViewer.test.js
@@ -0,0 +1,45 @@
+import React from 'react';
+import {renderWithProviders as render} from '../test-utils';
+import MapViewer from './MapViewer';
+
+// MapLibre needs WebGL, which jsdom lacks; these tests only cover what the viewer does to the URL.
+jest.mock('maplibre-gl', () => ({
+ __esModule: true,
+ default: {Map: class {
+ }, addProtocol: jest.fn(), Marker: class {
+ }, Popup: class {
+ }},
+}));
+jest.mock('maplibre-gl/dist/maplibre-gl.css', () => ({}));
+jest.mock('pmtiles', () => ({
+ __esModule: true, Protocol: class {
+ tile = jest.fn();
+ },
+}));
+jest.mock('protomaps-themes-base', () => ({__esModule: true, default: () => []}));
+jest.mock('@acalcutt/maplibre-contour-pmtiles', () => ({__esModule: true, default: {}}));
+jest.mock('../api', () => ({
+ ...jest.requireActual('../api'),
+ // Never resolves: the map never initializes, which these tests do not need.
+ getMapFiles: jest.fn(() => new Promise(() => {
+ })),
+ getMapPins: jest.fn(() => new Promise(() => {
+ })),
+}));
+
+describe('the map position in the URL', () => {
+ test('is removed when the map closes', () => {
+ const {unmount} = render(
, {route: '/map?lat=40&lon=-105&z=8&layer=a'});
+ unmount();
+ expect(window.location.pathname).toBe('/map');
+ expect(window.location.search).toBe('?layer=a');
+ });
+
+ test('is not removed from the page the map navigated to', () => {
+ // "Calculate Solar Performance" navigates to a page whose own lat/lon must survive the map closing.
+ const {unmount} = render(
, {route: '/map?lat=40&lon=-105&z=8'});
+ window.history.pushState({}, '', '/more/calculators?calc=solar&lat=40.0154&lon=-105.2705');
+ unmount();
+ expect(window.location.search).toBe('?calc=solar&lat=40.0154&lon=-105.2705');
+ });
+});
diff --git a/app/src/components/calculators/SolarCalculator.js b/app/src/components/calculators/SolarCalculator.js
new file mode 100644
index 00000000..c0e1ca42
--- /dev/null
+++ b/app/src/components/calculators/SolarCalculator.js
@@ -0,0 +1,625 @@
+import React from "react";
+import {useSearchParams} from "react-router";
+import {
+ Accordion,
+ Button,
+ Grid,
+ Group,
+ Header,
+ IconButton,
+ Loader,
+ Message,
+ NumberInput,
+ Panel,
+ Select,
+ Statistic,
+ StatisticGroup,
+ Table,
+ Tabs,
+ TextInput,
+ Toggle,
+} from "../ui";
+import {InfoPopup, roundDigits} from "../Common";
+import {
+ DEFAULT_LOSSES,
+ defaultAzimuth,
+ estimateProduction,
+ formatMonthly,
+ INVERTER_NOMINAL_EFFICIENCY,
+ LOSS_CATEGORIES,
+ MODULE_TYPES,
+ MONTH_NAMES,
+ MOUNTINGS,
+ optimalTilt,
+ parseCoordinate,
+ parseMonthly,
+ totalLoss,
+ TRACKING,
+} from "./solar";
+import {
+ CLIMATOLOGY_ACKNOWLEDGMENT,
+ CLIMATOLOGY_CHANGES,
+ CLIMATOLOGY_DATA_REFERENCE,
+ CLIMATOLOGY_LICENSE,
+ lookupClimatology,
+ useClimatology,
+} from "./solarData";
+import {SolarOffGrid} from "./SolarOffGrid";
+
+// Every input lives in the URL query so the Share button (which shares window.location.href) shares
+// the whole configuration. Values equal to their default are left out to keep the URL, and its QR
+// code, small. Keys are short and must stay stable; shared links depend on them.
+const DEFAULT_PANEL_WATTS = 400;
+const DEFAULT_PANEL_COUNT = 1;
+
+const COMPASS = [
+ {value: '0', label: 'N'}, {value: '45', label: 'NE'}, {value: '90', label: 'E'}, {value: '135', label: 'SE'},
+ {value: '180', label: 'S'}, {value: '225', label: 'SW'}, {value: '270', label: 'W'}, {value: '315', label: 'NW'},
+];
+
+const fToC = f => (f - 32) * 5 / 9;
+const cToF = c => c * 9 / 5 + 32;
+
+const numberOr = (value, fallback) => {
+ if (value === null || value === undefined || value === '') {
+ return fallback;
+ }
+ const n = Number(value);
+ return Number.isFinite(n) ? n : fallback;
+};
+
+const fmt = (value, digits = 2) => (Number.isFinite(value) ? `${roundDigits(value, digits)}` : '—');
+
+// Read and write the calculator's query parameters. Writes replace the history entry, so typing does
+// not fill the Back button with one entry per keystroke.
+export function useSolarParams() {
+ const [searchParams, setSearchParams] = useSearchParams();
+
+ const get = key => searchParams.get(key);
+
+ // `updates` maps keys to values; null, undefined and '' remove the key.
+ const set = updates => setSearchParams(prev => {
+ const next = new URLSearchParams(prev);
+ Object.entries(updates).forEach(([key, value]) => {
+ if (value === null || value === undefined || value === '') {
+ next.delete(key);
+ } else {
+ next.set(key, `${value}`);
+ }
+ });
+ return next;
+ }, {replace: true});
+
+ // Store a number, or remove it when it equals the default.
+ const setNumber = (key, value, fallback) =>
+ set({[key]: value === '' || Number(value) === fallback ? null : value});
+
+ return {searchParams, get, set, setNumber};
+}
+
+// Turn the query parameters into the model's inputs. Invalid values fall back to defaults, so a
+// hand-edited or truncated link never crashes the page.
+export function systemFromParams(get) {
+ const latitude = parseCoordinate(get('lat'), 'lat');
+ const longitude = parseCoordinate(get('lon'), 'lon');
+ const fahrenheit = get('tu') === 'f';
+
+ // Own sunlight data replaces the NASA data when present.
+ const ownData = get('ghi') !== null;
+ const ghi = parseMonthly(get('ghi')).map(v => (v !== null && v >= 0 ? v : null));
+ const temperatureInput = parseMonthly(get('temp'));
+ const temperature = temperatureInput.map(v => (v === null ? null : (fahrenheit ? fToC(v) : v)));
+
+ const panelWatts = Math.max(0, numberOr(get('pw'), DEFAULT_PANEL_WATTS));
+ const panelCount = Math.max(0, Math.round(numberOr(get('pn'), DEFAULT_PANEL_COUNT)));
+ const kwp = panelWatts * panelCount / 1000;
+
+ const tracking = TRACKING[get('track')] ? get('track') : 'fixed';
+ const mounting = MOUNTINGS[get('mount')] ? get('mount') : 'open';
+ const gamma = numberOr(get('gamma'), MODULE_TYPES.standard.gamma);
+ const defaultTilt = latitude === null ? 0 : Math.round(Math.abs(latitude));
+ const tilt = Math.min(90, Math.max(0, numberOr(get('tilt'), defaultTilt)));
+ const azimuth = numberOr(get('az'), defaultAzimuth(latitude ?? 0));
+ // Null means "use the monthly albedo from the data", which includes seasonal snow.
+ const albedoInput = numberOr(get('alb'), null);
+ const albedo = albedoInput === null ? null : Math.min(1, Math.max(0, albedoInput));
+
+ const lossValues = parseMonthly(get('losses'));
+ const losses = LOSS_CATEGORIES.map((c, i) => {
+ const v = lossValues[i];
+ return v !== null && v >= 0 && v <= 100 ? v : c.default;
+ });
+
+ const inverterOn = get('inv') === '1';
+ const acRating = numberOr(get('iac'), roundDigits(kwp / 1.2, 2));
+ const efficiency = numberOr(get('ieff'), INVERTER_NOMINAL_EFFICIENCY);
+
+ return {
+ latitude, longitude, fahrenheit, ownData, ghi, temperatureInput, temperature, panelWatts, panelCount,
+ kwp, tracking, mounting, gamma, defaultTilt, tilt, azimuth, albedo, losses, inverterOn, acRating,
+ efficiency,
+ };
+}
+
+// The sunlight inputs for the model: the user's own values, or the NASA data at the location.
+export function sunlightFor(s, grid) {
+ if (s.ownData) {
+ return {ghi: s.ghi, diffuse: null, temperature: s.temperature, albedo: null};
+ }
+ if (!grid || s.latitude === null || s.longitude === null) {
+ return null;
+ }
+ return lookupClimatology(grid, s.latitude, s.longitude);
+}
+
+// What stops an estimate, or an empty list when it can run.
+export function missingInputs(s, sunlight) {
+ const missing = [];
+ if (s.latitude === null) {
+ missing.push('a latitude');
+ }
+ if (!s.ownData && s.longitude === null) {
+ missing.push('a longitude');
+ }
+ if (s.ownData && s.ghi.some(v => v === null)) {
+ missing.push('sunlight for all 12 months');
+ }
+ if (!(s.kwp > 0)) {
+ missing.push('panel watts and count');
+ }
+ if (missing.length === 0 && (!sunlight || sunlight.ghi.some(v => v === null))) {
+ missing.push('a location with sunlight data');
+ }
+ return missing;
+}
+
+const modelInputs = (s, sunlight) => ({
+ latitude: s.latitude,
+ ghi: sunlight.ghi,
+ diffuse: sunlight.diffuse,
+ temperature: sunlight.temperature,
+ albedo: s.albedo ?? sunlight.albedo ?? undefined,
+ kwp: s.kwp,
+ tilt: s.tilt,
+ azimuth: s.azimuth,
+ tracking: s.tracking,
+ mounting: s.mounting,
+ gamma: s.gamma,
+ losses: s.losses,
+ inverter: s.inverterOn ? {acRating: s.acRating, efficiency: s.efficiency} : null,
+});
+
+const compassLabel = azimuth => {
+ const exact = COMPASS.find(c => Number(c.value) === azimuth);
+ return exact ? exact.label : `${azimuth}°`;
+};
+
+// Small explanatory text at the top of a collapsed section.
+const Hint = ({children}) =>
{children}
;
+
+// NASA POWER's requested acknowledgment, the license, and how WROLPi changed the data (CC BY 4.0).
+function DataAttribution() {
+ return
+
+ {CLIMATOLOGY_ACKNOWLEDGMENT} {CLIMATOLOGY_DATA_REFERENCE}
+ License: {CLIMATOLOGY_LICENSE}
+ {CLIMATOLOGY_CHANGES}
+ ;
+}
+
+const ESTIMATE_INFO = 'A typical-year estimate from monthly averages. Real years vary; expect roughly ±10–15% '
+ + 'over a year and more in any single month. Shading from trees and buildings is not modeled beyond the '
+ + 'Shading loss.';
+
+// Browsers only offer geolocation to pages served over HTTPS.
+export const geolocationAvailable = () => Boolean(window.isSecureContext && navigator.geolocation);
+
+const GEOLOCATION_ERRORS = {
+ 1: 'Location permission was denied. Allow it in your browser\'s settings for this site.',
+ 2: 'Your device could not find its location. Phones with GPS work offline; most computers need the Internet '
+ + 'for this.',
+ 3: 'Finding your location took too long. Phones with GPS work offline; most computers need the Internet for '
+ + 'this.',
+};
+
+function LocationSection({get, set, s, climatology}) {
+ const [locating, setLocating] = React.useState(false);
+ const [geoError, setGeoError] = React.useState(null);
+ const latError = get('lat') && s.latitude === null ? 'Latitude must be between -90 and 90' : null;
+ const lonError = get('lon') && s.longitude === null ? 'Longitude must be between -180 and 180' : null;
+
+ const locate = () => {
+ setLocating(true);
+ setGeoError(null);
+ navigator.geolocation.getCurrentPosition(
+ ({coords}) => {
+ setLocating(false);
+ // 4 decimals (about 11 m) is far finer than the 1° data and keeps the shared URL short.
+ set({lat: Number(coords.latitude.toFixed(4)), lon: Number(coords.longitude.toFixed(4))});
+ },
+ error => {
+ setLocating(false);
+ setGeoError(GEOLOCATION_ERRORS[error.code] || error.message);
+ },
+ {enableHighAccuracy: false, timeout: 20000, maximumAge: 10 * 60 * 1000},
+ );
+ };
+
+ // The data's attribution is at the bottom of the page; this line only reports the data's state.
+ let source = null;
+ if (s.ownData) {
+ source = 'Using your own sunlight data.';
+ } else if (climatology.loading) {
+ source =
;
+ } else if (climatology.error) {
+ source =
+ Enter your own monthly sunlight under "Use my own sunlight data" below.
+ ;
+ }
+
+ return <>
+
+
+
+
+
+
+ set({lat: e.target.value})}/>
+
+
+ set({lon: e.target.value})}/>
+
+
+ {geoError &&
{geoError} }
+ {source &&
{source}
}
+ ;
+}
+
+function PanelsSection({setNumber, s}) {
+ return <>
+
+
+
+ setNumber('pw', v, DEFAULT_PANEL_WATTS)}/>
+
+
+ setNumber('pn', v, DEFAULT_PANEL_COUNT)}/>
+
+
+
+ {fmt(s.kwp * 1000, 0)} W total ({fmt(s.kwp)} kW)
+
+
+
+ ;
+}
+
+function Results({result, s}) {
+ const unit = s.inverterOn ? 'kWh AC' : 'kWh DC';
+ const rows = result.months.map(m =>
+ {m.month}
+ {fmt(m.energyDaily)}
+ {fmt(m.energy, 0)}
+ {fmt(m.poa)}
+ {fmt(m.dayLength, 1)} h
+ );
+
+ return
+
+
+
+
+
+
+ Month
+ {unit}/day
+ {unit}/month
+ Sun hours on panel
+ Day length
+
+
+ {rows}
+
+ ;
+}
+
+function AngleSection({setNumber, s, sunlight, ready}) {
+ const compass = COMPASS.find(c => Number(c.value) === s.azimuth)?.value || null;
+ const applyOptimal = goal => setNumber('tilt', optimalTilt(modelInputs(s, sunlight), goal), s.defaultTilt);
+ const azimuthDefault = defaultAzimuth(s.latitude ?? 0);
+
+ if (s.tracking !== 'fixed') {
+ return
+ A tracking array turns to follow the sun, so it has no fixed angle. Change Tracking under Panel details
+ to set one.
+ ;
+ }
+
+ return <>
+
+ Leave these alone unless your panels are already mounted. The default (tilted to your latitude, facing
+ the equator) is close to the best for the year. "Best for winter" suits off-grid systems that must get
+ through the darkest month.
+
+
+
+ setNumber('tilt', v, s.defaultTilt)}/>
+
+ applyOptimal('annual')}>
+ Best for the year
+
+ applyOptimal('winter')}>
+ Best for winter
+
+
+
+
+
+ setNumber('az', v, azimuthDefault)}/>
+ setNumber('az', v, azimuthDefault)}/>
+
+
+
+ ;
+}
+
+function DetailsSection({set, setNumber, s}) {
+ const moduleType = Object.entries(MODULE_TYPES).find(([, m]) => m.gamma === s.gamma)?.[0] || 'custom';
+ return <>
+
+ The defaults suit a typical ground or pole mounted array of ordinary panels. The temperature coefficient
+ is on your panel's datasheet; panels lose this much power for each °C they run above 25 °C.
+
+
+
+ ({value, label: m.label})),
+ {value: 'custom', label: 'Custom (from datasheet)'},
+ ]}
+ value={moduleType} allowDeselect={false}
+ onChange={v => v !== 'custom' && setNumber('gamma', MODULE_TYPES[v].gamma,
+ MODULE_TYPES.standard.gamma)}/>
+
+
+ setNumber('gamma', v, MODULE_TYPES.standard.gamma)}/>
+
+
+ ({value, label: m.label}))}
+ value={s.mounting} allowDeselect={false}
+ onChange={v => set({mount: v === 'open' ? null : v})}/>
+
+
+ ({value, label: t.label}))}
+ value={s.tracking} allowDeselect={false}
+ onChange={v => set({track: v === 'fixed' ? null : v})}/>
+
+
+ set({alb: v === '' ? null : v})}/>
+
+
+ ;
+}
+
+function LossesSection({set, s}) {
+ const setLoss = (index, value) => {
+ const next = [...s.losses];
+ next[index] = value === '' ? LOSS_CATEGORIES[index].default : Number(value);
+ const isDefault = next.every((v, i) => v === DEFAULT_LOSSES[i]);
+ set({losses: isDefault ? null : formatMonthly(next)});
+ };
+
+ return <>
+
+ Real systems lose some power to dirt, wiring, shading and more. These are PVWatts' defaults. Raise Shading
+ if trees or buildings shade your panels, or Snow if snow sits on them for weeks.
+
+
+ {LOSS_CATEGORIES.map((c, i) =>
+ setLoss(i, v)}/>
+ )}
+
+
set({losses: null})}>
+ Reset to PVWatts defaults
+
+ ;
+}
+
+function InverterSection({set, setNumber, s}) {
+ return <>
+
+ Leave this off if your panels charge batteries through a charge controller. Turn it on to see AC output
+ from a grid-tie or hybrid inverter.
+
+
set({inv: e.currentTarget.checked ? '1' : null})}/>
+ {s.inverterOn &&
+
+ setNumber('iac', v, roundDigits(s.kwp / 1.2, 2))}/>
+
+
+ setNumber('ieff', v, INVERTER_NOMINAL_EFFICIENCY)}/>
+
+ }
+ ;
+}
+
+function OwnDataSection({set, s, nasa}) {
+ const unit = s.fahrenheit ? '°F' : '°C';
+
+ // Start from the NASA values, when available, so the user edits rather than types all 24.
+ const enable = on => {
+ if (!on) {
+ set({ghi: null, temp: null});
+ return;
+ }
+ const ghi = nasa ? nasa.ghi.map(v => (v === null ? '' : roundDigits(v, 2))) : Array(12).fill('');
+ const temp = nasa
+ ? nasa.temperature.map(v => (v === null ? '' : roundDigits(s.fahrenheit ? cToF(v) : v, 1)))
+ : Array(12).fill('');
+ // An all-blank list is still written for sunlight, so the section stays on for typing.
+ set({ghi: formatMonthly(ghi), temp: nasa ? formatMonthly(temp) : null});
+ };
+
+ // Convert the temperatures with the unit, so they stay the same physical temperatures.
+ const switchUnits = toFahrenheit => {
+ const temps = s.temperatureInput.map(v => (v === null ? null
+ : roundDigits(toFahrenheit ? cToF(v) : fToC(v), 1)));
+ set({tu: toFahrenheit ? 'f' : null, temp: temps.some(v => v !== null) ? formatMonthly(temps) : null});
+ };
+
+ const setMonth = (key, values, index, value) => {
+ const next = [...values];
+ next[index] = value === '' ? null : value;
+ set({[key]: formatMonthly(next)});
+ };
+
+ const rows = MONTH_NAMES.map((name, i) =>
+ {name}
+
+ setMonth('ghi', s.ghi, i, v)}/>
+
+
+ setMonth('temp', s.temperatureInput, i, v)}/>
+
+ );
+
+ return <>
+
+ Only needed if you have better local measurements than the built-in data, for example in mountains, where
+ a 1° grid cell (about 69 miles across) can average very different terrain. Sunlight is global horizontal
+ irradiance in kWh/m²/day, the same as "peak sun hours" on flat ground. Blank temperatures use 20 °C.
+
+
+ enable(e.currentTarget.checked)}/>
+ {s.ownData && switchUnits(e.currentTarget.checked)}/>}
+
+ {s.ownData &&
+
+
+ Month
+ Sunlight (kWh/m²/day)
+ Avg. temp ({unit})
+
+
+ {rows}
+
}
+ ;
+}
+
+export function SolarCalculator() {
+ const {searchParams, get, set, setNumber} = useSolarParams();
+ const climatology = useClimatology();
+ const queryString = searchParams.toString();
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ const s = React.useMemo(() => systemFromParams(get), [queryString]);
+ const nasa = React.useMemo(
+ () => (climatology.grid && s.latitude !== null && s.longitude !== null
+ ? lookupClimatology(climatology.grid, s.latitude, s.longitude) : null),
+ [climatology.grid, s.latitude, s.longitude]);
+ const sunlight = s.ownData ? sunlightFor(s, null) : nasa;
+ const missing = missingInputs(s, sunlight);
+ const ready = missing.length === 0;
+ const result = React.useMemo(
+ () => (ready ? estimateProduction(modelInputs(s, sunlight)) : null),
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ [s, sunlight, ready]);
+ // Off-grid sizing works from DC production per kW of panels, whatever the inverter setting.
+ const worstPerKwp = React.useMemo(
+ () => (ready ? estimateProduction({...modelInputs(s, sunlight), kwp: 1, inverter: null}).worst : null),
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ [s, sunlight, ready]);
+ const tab = get('tab') === 'offgrid' ? 'offgrid' : 'estimate';
+
+ const angleTitle = s.tracking === 'fixed'
+ ? `Panel angle: ${s.tilt}° tilt, facing ${compassLabel(s.azimuth)}`
+ : 'Panel angle: follows the sun';
+ const detailsTitle = `Panel details: ${TRACKING[s.tracking].label.toLowerCase()}, `
+ + `${MOUNTINGS[s.mounting].label.toLowerCase()}`;
+ const waitingForData = climatology.loading && !s.ownData;
+
+ return
+
+
+ Estimate what solar panels will produce over a typical year. Enter a location and your panels; everything
+ else has sensible defaults. Settings are saved in the page address, so you can bookmark or share them.
+
+
+
+
+
+ set({tab: v === 'offgrid' ? v : null})} keepMounted={false}
+ style={{marginTop: '1.5em'}}>
+
+ Estimate
+ Off-grid sizing
+
+
+ {ready && }
+ {!ready && !waitingForData &&
+ Enter {missing.join(', ')} to see an estimate.
+
}
+
+
+
+
+
+
+
+
+
+ {angleTitle}
+
+
+
+
+
+ {detailsTitle}
+
+
+ System losses: {fmt(totalLoss(s.losses))}%
+
+
+ Inverter: {s.inverterOn ? 'on (AC output)' : 'off (DC output)'}
+
+
+ Use my own sunlight data: {s.ownData ? 'on' : 'off'}
+
+
+
+ {children}
;
+
+// The off-grid inputs, read from the URL like the rest of the calculator. Invalid values fall back.
+export function offGridFromParams(get, monthlyTemperatures) {
+ const battery = BATTERIES[get('bat')] ? get('bat') : 'lfp';
+ const systemVoltage = SYSTEM_VOLTAGES.includes(Number(get('sv'))) ? Number(get('sv')) : 12;
+ const controller = CONTROLLERS[get('ctl')] ? get('ctl') : 'mppt';
+ const coldestMonthly = (monthlyTemperatures || []).filter(Number.isFinite).length
+ ? Math.min(...monthlyTemperatures.filter(Number.isFinite)) : null;
+ const defaultTmin = defaultColdest(monthlyTemperatures);
+ return {
+ loads: parseLoads(get('load')),
+ acLoads: get('ac') !== '0',
+ loadInverterEfficiency: numberOr(get('leff'), DEFAULT_LOAD_INVERTER_EFFICIENCY),
+ battery,
+ systemVoltage,
+ dod: numberOr(get('dod'), BATTERIES[battery].dod),
+ days: Math.max(0, numberOr(get('aut'), DEFAULT_DAYS)),
+ outdoors: get('bout') === '1',
+ controller,
+ voc: numberOr(get('voc'), PANEL_DEFAULTS.voc),
+ vmp: numberOr(get('vmp'), PANEL_DEFAULTS.vmp),
+ isc: numberOr(get('isc'), PANEL_DEFAULTS.isc),
+ // Always negative for silicon panels; a missing minus sign must not hide the cold-weather rise.
+ betaVoc: -Math.abs(numberOr(get('bvoc'), PANEL_DEFAULTS.bvoc)),
+ series: Math.max(1, Math.round(numberOr(get('ns'), 1))),
+ controllerMaxVoltage: numberOr(get('cmax'), DEFAULT_CONTROLLER_MAX_VOLTAGE),
+ coldestMonthly,
+ defaultTmin,
+ coldest: numberOr(get('tmin'), defaultTmin),
+ };
+}
+
+/**
+ * Everything the off-grid tab shows, from its inputs.
+ *
+ * @param {Object} o offGridFromParams()
+ * @param {Object} worst the worst month for a 1 kW array: {month, energyDaily}
+ * @param {number} panelWatts
+ * @param {number} panelCount
+ */
+export function offGridResults(o, worst, panelWatts, panelCount) {
+ const devicesWh = dailyLoadWh(o.loads);
+ // AC devices draw through an inverter, so the batteries supply more than the devices use.
+ const batteryLoadWh = o.acLoads && o.loadInverterEfficiency > 0
+ ? devicesWh / (o.loadInverterEfficiency / 100) : devicesWh;
+ const capacityFactor = o.outdoors && o.battery === 'lead' ? leadAcidCapacityFactor(o.coldestMonthly) : 1;
+ const bank = sizeBattery({
+ loadWh: batteryLoadWh, days: o.days, dod: o.dod, voltage: o.systemVoltage, capacityFactor,
+ });
+
+ const sizing = controllerSizing({
+ panelCount, panelWatts, series: o.series, voc: o.voc, vmp: o.vmp, isc: o.isc, betaVoc: o.betaVoc,
+ coldest: o.coldest, controller: o.controller, controllerMaxVoltage: o.controllerMaxVoltage,
+ systemVoltage: o.systemVoltage,
+ });
+
+ // A PWM controller wastes part of every panel's output, so more panels are needed.
+ const worstPerKwp = worst ? worst.energyDaily * sizing.pwmFraction : null;
+ const kwp = requiredKwp(batteryLoadWh, worstPerKwp, BATTERIES[o.battery].efficiency);
+ const panelsNeeded = kwp && panelWatts > 0 ? Math.ceil(kwp * 1000 / panelWatts) : null;
+ const yourArrayWh = worstPerKwp !== null
+ ? worstPerKwp * (panelCount * panelWatts / 1000) * 1000 * BATTERIES[o.battery].efficiency / 100 : null;
+
+ return {
+ devicesWh, batteryLoadWh, bank, kwp, panelsNeeded, sizing,
+ coverage: batteryLoadWh > 0 && yourArrayWh !== null ? yourArrayWh / batteryLoadWh : null,
+ warnings: batteryWarnings({battery: o.battery, outdoors: o.outdoors, coldestMonthly: o.coldestMonthly}),
+ };
+}
+
+function LoadsSection({o, r, set, setNumber}) {
+ const rows = o.loads.length ? o.loads : [{name: '', watts: '', hours: ''}];
+ const write = next => set({load: next.some(row => row.name || row.watts || row.hours) ? formatLoads(next) : null});
+ const update = (index, field, value) => write(rows.map((row, i) => (i === index ? {...row, [field]: value} : row)));
+ const remove = index => write(rows.filter((_, i) => i !== index));
+
+ return <>
+
+
+ List what you will run and for how long each day. The watts are on the device's label or power supply;
+ a refrigerator cycles on and off, so use about a third of its rating for 24 hours.
+
+
+
+
+ Device
+ Watts
+ Hours per day
+ Wh per day
+
+
+
+ {rows.map((row, i) =>
+
+ update(i, 'name', e.target.value)}/>
+
+
+ update(i, 'watts', v)}/>
+
+
+ update(i, 'hours', v)}/>
+
+ {fmt(loadWh(row))}
+
+ remove(i)}/>
+
+ )}
+
+
+
+ write([...rows, {name: '', watts: '', hours: ''}])}>
+ Add device
+
+ {fmt(r.devicesWh)} Wh per day
+
+ set({ac: e.currentTarget.checked ? null : '0'})}/>
+ {o.acLoads && setNumber('leff', v, DEFAULT_LOAD_INVERTER_EFFICIENCY)}/>}
+
+ ;
+}
+
+function BatterySection({o, set, setNumber}) {
+ return <>
+
+
+ Days without sun is how long the batteries must carry your devices through cloudy weather. Two or three
+ days is typical. Larger systems (over about 1,500 W of panels) usually use 24 or 48 volts.
+
+
+
+ ({value, label: b.label}))}
+ value={o.battery} allowDeselect={false}
+ onChange={v => set({bat: v === 'lfp' ? null : v, dod: null})}/>
+
+
+ ({value: `${v}`, label: `${v} V`}))}
+ value={`${o.systemVoltage}`} allowDeselect={false}
+ onChange={v => set({sv: v === '12' ? null : v})}/>
+
+
+ setNumber('aut', v, DEFAULT_DAYS)}/>
+
+
+ setNumber('dod', v, BATTERIES[o.battery].dod)}/>
+
+
+ set({bout: e.currentTarget.checked ? '1' : null})}/>
+
+
+ ;
+}
+
+function NeedsSection({o, r, worst, s, setNumber}) {
+ if (!(r.devicesWh > 0)) {
+ return
+ List your devices above to size the system.
+
;
+ }
+ const coverage = r.coverage;
+ return
+
+
+
+
+ Sized for {worst.month}, your darkest month, when each kW of panels makes about{' '}
+ {fmt(worst.energyDaily, 1)} kWh a day at the angle chosen under Fine-tune.
+ {o.controller === 'pwm' && r.sizing.pwmFraction > 0 && ` The PWM controller uses only `
+ + `${fmt(r.sizing.pwmFraction * 100)}% of the panels' power, so more panels are needed.`}
+ {o.controller === 'pwm' && r.sizing.pwmFraction === 0 && ' These panels cannot charge this battery '
+ + 'through a PWM controller; see the warning below.'}
+
+ {coverage !== null &&
+ Your {s.panelCount} panel{s.panelCount === 1 ? '' : 's'} would supply about{' '}
+ {fmt(Math.min(coverage, 9.99) * 100)}% of your use in {worst.month}.{' '}
+ {r.panelsNeeded !== s.panelCount && r.panelsNeeded > 0 &&
+ setNumber('pn', r.panelsNeeded, 1)}>
+ Use {r.panelsNeeded} panels
+ }
+
}
+ {r.warnings.map(w => {w} )}
+ ;
+}
+
+function ControllerSection({o, r, set, setNumber, temperaturesKnown}) {
+ const z = r.sizing;
+ const panelField = (key, label, value, fallback, step, max) =>
+ setNumber(key, v, fallback)}/>
+ ;
+
+ return <>
+ Charge controller and wiring
+
+ Copy these from the label on the back of your panel. Panels make a higher voltage when cold; too many in
+ series can exceed the controller's limit on a cold morning and destroy it. The coldest morning starts
+ 25 °C below your coldest monthly average, because averages hide cold snaps; enter your area's record
+ low if you know it.
+
+
+ {panelField('voc', 'Open-circuit voltage, Voc (V)', o.voc, PANEL_DEFAULTS.voc, 0.1)}
+ {panelField('vmp', 'Max-power voltage, Vmp (V)', o.vmp, PANEL_DEFAULTS.vmp, 0.1)}
+ {panelField('isc', 'Short-circuit current, Isc (A)', o.isc, PANEL_DEFAULTS.isc, 0.1)}
+ {panelField('bvoc', 'Voc temperature coefficient (%/°C)', o.betaVoc, PANEL_DEFAULTS.bvoc, 0.01, 0)}
+
+ ({value, label: c.label}))}
+ value={o.controller} allowDeselect={false}
+ onChange={v => set({ctl: v === 'mppt' ? null : v})}/>
+
+
+ setNumber('cmax', v, DEFAULT_CONTROLLER_MAX_VOLTAGE)}/>
+
+
+ setNumber('ns', v, 1)}/>
+
+
+ setNumber('tmin', v, o.defaultTmin)}/>
+
+
+ {/* The cold-morning limit depends on the site's temperatures; do not show a placeholder's verdict. */}
+ {!temperaturesKnown &&
}
+ {temperaturesKnown && <>
+
+
+
+ Strings
+ {z.strings} of {o.series} panel{o.series === 1 ? '' : 's'} in series
+
+
+ String voltage on the coldest morning
+ {fmt(z.stringColdVoc, 1)} V (most panels in series: {z.maxSeries})
+
+
+ Controller current rating, at least
+ {fmt(z.current)} A
+
+
+
+ {z.overVoltage &&
+ {o.series} panels in series reach {fmt(z.stringColdVoc, 1)} V on a {o.coldest} °C morning,
+ over the controller's {o.controllerMaxVoltage} V limit. Use at most {z.maxSeries} in series, or a
+ controller rated for more voltage.
+ }
+ {z.lowVoltage &&
+ {o.controller === 'pwm' && z.pwmFraction === 0
+ ? `${o.series} panel${o.series === 1 ? '' : 's'} in series cannot reach the ${o.systemVoltage} V `
+ + 'battery\'s charging voltage, so a PWM controller cannot charge it at all.'
+ : `On a hot day ${o.series} panel${o.series === 1 ? '' : 's'} in series may not stay far enough `
+ + 'above the battery\'s charging voltage for the controller to charge well.'}
+ {' '}Put more panels in series, or use a lower system voltage.
+ }
+ {z.unevenStrings &&
+ Your panel count does not divide evenly into strings of {o.series}. Every string should have the same
+ number of panels.
+ }
+ {o.controller === 'mppt' && z.current > HIGH_CURRENT && o.systemVoltage < 48 &&
+
+ {fmt(z.current)} A needs a large controller and thick wire. A higher system voltage would cut the
+ current.
+ }
+ }
+ ;
+}
+
+/**
+ * The off-grid sizing tab.
+ *
+ * @param {Object} worst the worst month for a 1 kW DC array, or null when there is no estimate
+ * @param {number[]} temperatures monthly average temperatures at the site, °C
+ * @param {boolean} loading the built-in sunlight and temperature data is still downloading
+ */
+export function SolarOffGrid({get, set, setNumber, s, worst, temperatures, loading}) {
+ const o = offGridFromParams(get, temperatures);
+ const r = offGridResults(o, worst, s.panelWatts, s.panelCount);
+
+ return
+
+ Size a battery system to run your devices through the darkest month. Production here is DC; the
+ Inverter section under Fine-tune is for grid-tie systems and does not apply.
+
+
+
+ {worst && }
+ {!worst && loading &&
}
+ {!worst && !loading &&
+ Enter a location above to size the system.
+
}
+ = {
'comments': 'IconMessages',
'copy': 'IconCopy',
'cube': 'IconCube',
+ 'current location': 'IconCurrentLocation',
'directory': 'IconFolder',
'disk': 'IconDatabase',
'dot circle': 'IconCircleDot',
diff --git a/docker/help/wrolpi-help b/docker/help/wrolpi-help
index c4362d80..b61bae30 160000
--- a/docker/help/wrolpi-help
+++ b/docker/help/wrolpi-help
@@ -1 +1 @@
-Subproject commit c4362d807977c2719dbe9a870ad86f4c14580431
+Subproject commit b61bae309cf253e080824ac12eb8b4fb690b8456
diff --git a/scripts/build_solar_climatology.py b/scripts/build_solar_climatology.py
new file mode 100644
index 00000000..2fd4654e
--- /dev/null
+++ b/scripts/build_solar_climatology.py
@@ -0,0 +1,216 @@
+#!/usr/bin/env python3
+"""
+Build the offline solar climatology used by the Solar calculator.
+
+Downloads NASA POWER's 2001-2020 monthly climatology for the whole globe and packs it into
+app/public/data/solar-climatology.bin, which the React app fetches when the Solar calculator opens.
+This needs the Internet and is run by a developer; WROLPi never runs it. The output only changes
+when NASA publishes a new climatology period, so regenerating it should be rare.
+
+ python3 scripts/build_solar_climatology.py
+
+Downloaded tiles are cached (see --cache), so an interrupted run resumes where it stopped.
+
+NASA POWER data is licensed CC BY 4.0. The build also writes solar-climatology.LICENSE.txt beside the
+data, crediting NASA as it asks (https://power.larc.nasa.gov/docs/referencing/), with the API version,
+the date the data was downloaded, and how WROLPi changed it.
+
+File format (all integers little-endian), decoded by app/src/components/calculators/solarData.js:
+
+ bytes 0-3 b"WSOL"
+ byte 4 format version (1)
+ byte 5 number of parameters (4)
+ bytes 6-7 reserved (0)
+ then uint8 values, [parameter][month][row][column]
+
+Rows are 1° latitude bands centered on -89.5 ... 89.5 (south to north), columns are 1° longitude
+bands centered on -179.5 ... 179.5 (west to east). 255 means no data. Each parameter is stored as
+round((value + offset) / step); see PARAMETERS.
+"""
+import argparse
+import datetime
+import json
+import math
+import pathlib
+import struct
+import sys
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from concurrent.futures import ThreadPoolExecutor, as_completed
+
+REPO = pathlib.Path(__file__).resolve().parent.parent
+DEFAULT_OUTPUT = REPO / 'app/public/data/solar-climatology.bin'
+DEFAULT_CACHE = REPO / 'scripts/.solar_climatology_cache'
+
+API = 'https://power.larc.nasa.gov/api/temporal/climatology/regional'
+# The regional endpoint accepts at most a 10° x 10° box and one parameter per request.
+TILE = 10
+MONTHS = ['JAN', 'FEB', 'MAR', 'APR', 'MAY', 'JUN', 'JUL', 'AUG', 'SEP', 'OCT', 'NOV', 'DEC']
+ROWS, COLUMNS = 180, 360
+MISSING = 255
+VERSION = 1
+
+# NASA's requested acknowledgment. Must match CLIMATOLOGY_ACKNOWLEDGMENT in solarData.js.
+ACKNOWLEDGMENT = ('The data was obtained from National Aeronautics and Space Administration (NASA) Langley '
+ 'Research Center\'s Prediction Of Worldwide Energy Resources (POWER) project funded through the '
+ 'NASA Earth Science Division.')
+LICENSE = 'Creative Commons Attribution 4.0 International (CC BY 4.0), https://creativecommons.org/licenses/by/4.0/'
+# CC BY 4.0 requires saying what was changed. Must match CLIMATOLOGY_CHANGES in solarData.js.
+CHANGES = ('WROLPi modified the data: values are rounded to fit one byte each (0.04 kWh/m²/day for irradiance, '
+ '0.004 for albedo, 0.5 °C for temperature), temperatures are averaged from NASA\'s 0.5° x 0.625° grid '
+ 'into 1° cells, and the calculator interpolates between cells.')
+
+# (NASA parameter, offset, step). Must match PARAMETERS in solarData.js, in the same order.
+PARAMETERS = [
+ ('ALLSKY_SFC_SW_DWN', 0, 0.04), # global horizontal, kWh/m²/day, 0-10.16
+ ('ALLSKY_SFC_SW_DIFF', 0, 0.04), # diffuse horizontal, kWh/m²/day
+ ('ALLSKY_SRF_ALB', 0, 0.004), # surface albedo, 0-1.016
+ ('T2M', 70, 0.5), # air temperature at 2 m, °C, -70 to +57
+]
+
+
+def tile_url(parameter, lat_min, lon_min):
+ query = urllib.parse.urlencode({
+ 'parameters': parameter,
+ 'community': 'RE',
+ 'latitude-min': lat_min,
+ 'latitude-max': lat_min + TILE,
+ 'longitude-min': lon_min,
+ 'longitude-max': lon_min + TILE,
+ 'format': 'JSON',
+ })
+ return f'{API}?{query}'
+
+
+def tile_path(cache, parameter, lat_min, lon_min):
+ return cache / f'{parameter}_{lat_min}_{lon_min}.json'
+
+
+def fetch_tile(parameter, lat_min, lon_min, cache, pause, retries=8):
+ """Return the tile's GeoJSON, from the cache when possible.
+
+ NASA rate limits the API (HTTP 429); back off for up to 10 minutes rather than give up, since a
+ full build is about 2,600 requests.
+ """
+ path = tile_path(cache, parameter, lat_min, lon_min)
+ if path.is_file():
+ return json.loads(path.read_text())
+
+ delay = 30
+ for attempt in range(retries):
+ try:
+ time.sleep(pause)
+ with urllib.request.urlopen(tile_url(parameter, lat_min, lon_min), timeout=180) as response:
+ data = json.loads(response.read())
+ if 'features' not in data:
+ raise ValueError(f'No features: {data.get("messages")}')
+ path.write_text(json.dumps(data))
+ return data
+ except (urllib.error.URLError, TimeoutError, ValueError) as e:
+ if attempt == retries - 1:
+ raise
+ print(f' retrying {parameter} {lat_min},{lon_min} in {delay}s: {e}', file=sys.stderr, flush=True)
+ time.sleep(delay)
+ delay = min(delay * 2, 600)
+
+
+def bin_points(points):
+ """Average points into 1° cells. `points` maps (lon, lat) to 12 monthly values.
+
+ Solar parameters are already on the 1° grid (one point per cell). Temperature comes on a finer
+ 0.5° x 0.625° grid, so several points average into each cell.
+ """
+ sums = {}
+ for (lon, lat), values in points.items():
+ row = min(ROWS - 1, max(0, math.floor(lat + 90)))
+ column = math.floor(lon + 180) % COLUMNS
+ cell = sums.setdefault((row, column), [[0.0, 0] for _ in MONTHS])
+ for month, value in enumerate(values):
+ if value is not None:
+ cell[month][0] += value
+ cell[month][1] += 1
+ return {cell: [s / n if n else None for s, n in months] for cell, months in sums.items()}
+
+
+def notice(api, accessed):
+ """The attribution written beside the data. `api` is like "POWER Climatology API v2.10.0"."""
+ parameters = ', '.join(p for p, _, _ in PARAMETERS)
+ return (
+ 'Solar climatology for the WROLPi Solar calculator\n'
+ '\n'
+ 'Source: NASA POWER, https://power.larc.nasa.gov/\n'
+ f'Data: 2001-2020 monthly climatology of {parameters}, on a 1° grid.\n'
+ f'The data was obtained from the POWER Project\'s {api} version on {accessed:%Y/%m/%d}.\n'
+ '\n'
+ f'{ACKNOWLEDGMENT}\n'
+ '\n'
+ f'License: {LICENSE}\n'
+ '\n'
+ f'Changes: {CHANGES}\n'
+ )
+
+
+def quantize(value, offset, step):
+ if value is None:
+ return MISSING
+ return max(0, min(MISSING - 1, round((value + offset) / step)))
+
+
+def main():
+ parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+ parser.add_argument('--output', type=pathlib.Path, default=DEFAULT_OUTPUT)
+ parser.add_argument('--cache', type=pathlib.Path, default=DEFAULT_CACHE)
+ parser.add_argument('--workers', type=int, default=1, help='Concurrent requests; NASA rate limits the API.')
+ parser.add_argument('--pause', type=float, default=1.0, help='Seconds to wait before each request.')
+ args = parser.parse_args()
+ args.cache.mkdir(parents=True, exist_ok=True)
+
+ tiles = [(lat, lon) for lat in range(-90, 90, TILE) for lon in range(-180, 180, TILE)]
+ out = bytearray(b'WSOL' + struct.pack('