diff --git a/.github/workflows/.ciyml b/.github/workflows/.ciyml
deleted file mode 100644
index f345d3e..0000000
--- a/.github/workflows/.ciyml
+++ /dev/null
@@ -1,28 +0,0 @@
-name: CI
-
-on:
- push:
- branches: ["**"]
- pull_request:
-
-jobs:
- test-and-build:
- runs-on: ubuntu-latest
- steps:
- - uses: actions/checkout@v4
- - uses: actions/setup-node@v4
- with:
- node-version: "20"
- cache: "npm"
- - run: npm ci
- - name: Unit tests (physics invariants)
- run: npm test
- - name: Production build
- run: npm run build
- - name: Standalone single-file build
- run: npm run build:standalone
- - name: Upload standalone artifact
- uses: actions/upload-artifact@v4
- with:
- name: solar-iv-lab-standalone
- path: dist-standalone/index.html
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..2ee243a
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,42 @@
+name: CI
+
+on:
+ push:
+ branches: [main]
+ pull_request:
+
+permissions:
+ contents: read
+
+concurrency:
+ group: solavin-ci-${{ github.ref }}
+ cancel-in-progress: true
+
+jobs:
+ test-and-build:
+ runs-on: ubuntu-latest
+ timeout-minutes: 20
+ steps:
+ - uses: actions/checkout@v4
+ - uses: actions/setup-node@v4
+ with:
+ node-version: "22"
+ cache: "npm"
+ - run: npm ci
+ - name: Dependency audit
+ run: npm audit --audit-level=high
+ - name: Scientific validation and coverage gates
+ run: npm run test:coverage
+ - name: Production and standalone builds
+ run: npm run build:all
+ - name: Install Chromium
+ run: npx playwright install --with-deps chromium
+ - name: Browser integration test
+ run: node tests/e2e.smoke.mjs
+ - name: Upload standalone artifact
+ uses: actions/upload-artifact@v4
+ with:
+ name: solavin-v4-standalone
+ path: dist-standalone/index.html
+ if-no-files-found: error
+ retention-days: 14
diff --git a/CITATION.cff b/CITATION.cff
new file mode 100644
index 0000000..5b50c1b
--- /dev/null
+++ b/CITATION.cff
@@ -0,0 +1,12 @@
+cff-version: 1.2.0
+message: "If you use Solavin in research, please cite the software and record the exact analysis version."
+title: "Solavin: Photovoltaic Characterization and Analysis Suite"
+type: software
+version: 4.0.0
+date-released: 2026-07-29
+authors:
+ - family-names: Uy
+ given-names: John Myron
+repository-code: "https://github.com/dev-juy/project-solavin"
+url: "https://github.com/dev-juy/project-solavin"
+license: MIT
diff --git a/README.md b/README.md
index 4c0b198..2ba1d24 100644
--- a/README.md
+++ b/README.md
@@ -1,144 +1,170 @@
-# project-solavin# Solavin — Photovoltaic Characterization Suite
-
-A lab-grade web application for analysing photovoltaic **current–voltage (I-V)**
-sweeps. Upload measured data, and Solavin extracts the standard figures of
-merit — short-circuit current (Isc ), open-circuit voltage
-(Voc ), maximum power (Pmax ), fill factor (FF), series and
-shunt resistance (Rs , Rsh ) and power-conversion efficiency
-(η) — with interactive I-V / P-V / radar visualisations and one-click CSV/Excel
-export.
-
-Built with React 18 + Vite + Recharts. The scientific core is plain,
-dependency-free JavaScript covered by an automated test suite, so results are
-reproducible and verifiable.
-
-> Developed by **John Myron Uy**, under the guidance of **Prof. Raymund Sarmiento** —
-> Research Laboratory, Solar Cell Characterization.
-
----
-
-## Highlights
-
-- **Parameter extraction** — Isc , Voc , Pmax ,
- Vmp , Imp , FF, Rs , Rsh , η.
-- **Multi-channel** — load many sweep conditions per dataset and compare them.
-- **Visualisations** — I-V, P-V (with MPP markers), normalised radar profile,
- and ranked Pmax comparison; brush-to-zoom and a voltage cursor
- lookup.
-- **Data ingest** — drag-and-drop `.xlsx` / `.xls` / `.csv`; multi-sheet picker.
-- **Export** — CSV and XLSX of the full metrics table, including η when area and
- irradiance are supplied.
-- **Lab Assistant** — an offline, deterministic analyser that answers from the
- extracted metrics (summaries, rankings, fill-factor interpretation, suggested
- experiments). No external API, no keys.
-- **Local operator profiles** — name a session to keep a persistent dataset
- library in your browser, or work in demo mode. No passwords, no backend.
-- **Two build targets** — a normal web app for hosting, and a single
- self-contained `.html` you can email or run offline from `file://`.
-
-## Accuracy & conventions
-
-Photovoltaic figures of merit are computed in
-[`src/lib/ivAnalysis.js`](src/lib/ivAnalysis.js) on the **signed** current
-(generator convention: current is positive in the power-producing quadrant and
-negative beyond Voc ).
-
-| Quantity | Definition used |
-|----------|-----------------|
-| Isc | Current at V = 0 (exact sample, else interpolated; extrapolated if the sweep starts above 0 V). |
-| Voc | Voltage at the first I = 0 crossing (linear interpolation). Flagged if it lies beyond the sweep range. |
-| Pmax , Vmp , Imp | Maximum of V·I, **restricted to the power quadrant** (V ≥ 0, I ≥ 0). |
-| FF | Pmax / (Isc · Voc ) — always < 1 for physical data. |
-| Rs | \|dV/dI\| near Voc (slope estimate). |
-| Rsh | \|dV/dI\| near Isc (slope estimate). |
-| η | Pmax / (G · A), with cell area in cm² and irradiance G in W/m². |
-
-Rs and Rsh are first-order slope estimates from a single
-light sweep; a dark I-V curve or a full single-diode fit gives more rigorous
-values.
-
-The test suite ([`src/lib/ivAnalysis.test.js`](src/lib/ivAnalysis.test.js))
-asserts these invariants on every build — including that the fill factor is
-always between 0 and 100 % — so the extraction cannot silently regress.
-
-## Data format
-
-Column **A** is voltage (volts); each subsequent column is one current sweep
-(amperes, signed). Row 1 holds headers, which become channel labels.
-
-```
-Voltage(V), Focused Laser, -2mm, +6mm Focus
-0, 1.539e-6, 1.46e-6, 1.583e-6
-0.05, 1.528e-6, 1.456e-6, 1.565e-6
-...
-2.5, -3.875e-6, -3.052e-6, -2.923e-6
+# Solavin
+
+Solavin is a research-oriented web application for inspecting photovoltaic
+current-voltage (I-V) sweeps. It extracts Isc , Voc ,
+Pmax , Vmp , Imp , fill factor, local slope
+estimates of Rs /Rsh , and—when area and irradiance are
+provided—power-conversion efficiency.
+
+The application is designed to make questionable data visible rather than turn
+it into precise-looking numbers. Missing cells remain missing, unbracketed
+Voc values are reported as lower bounds, dependent metrics are
+withheld when they cannot be supported, and every export carries analysis
+status and provenance.
+
+> Solavin validates calculations performed on supplied data. It does not
+> calibrate an instrument or certify a photovoltaic measurement to IEC 60904-1.
+> Measurement uncertainty, spectral mismatch, temperature control, irradiance
+> uniformity, sweep protocol, contact quality, and instrument calibration remain
+> the operator's responsibility.
+
+Developed by **John Myron Uy**, under the guidance of
+**Prof. Raymund Sarmiento** — Research Laboratory, Solar Cell
+Characterization.
+
+## What researchers get
+
+- Piecewise-linear I-V and P-V plots that do not invent smoothed extrema.
+- Exact maximum-power optimization on each measured linear segment.
+- Voltage-keyed alignment across sparse channels, so one missing cell cannot
+ shift later measurements onto the wrong voltage.
+- Explicit `pass`, `review`, and `invalid` channel states.
+- CSV and three-sheet XLSX exports:
+ - `Metrics` — values, units, per-metric status, quality flags, source, and
+ analysis version.
+ - `Raw Data` — signed measurements aligned by voltage with gaps preserved.
+ - `Metadata` — conventions, handling rules, source, and import warnings.
+- Safe `.xlsx` and RFC 4180 CSV ingestion with a 25 MB browser limit.
+- A deterministic offline assistant that only summarizes validated extracted
+ results.
+- A normal hosted build and a self-contained offline HTML build.
+
+## Analysis definitions
+
+All scientific calculations live in
+[`src/lib/ivAnalysis.js`](src/lib/ivAnalysis.js). Current uses the generator
+convention: current is positive while the device produces positive V·I power
+and negative beyond Voc .
+
+| Quantity | Definition and validity rule |
+|---|---|
+| Isc | Signed current at V = 0. Uses an exact sample, interpolation across zero, or a flagged nearest-pair extrapolation. |
+| Voc | First non-negative-voltage positive-to-negative current crossing, linearly interpolated. If no crossing is measured, the highest measured voltage is only a lower bound. |
+| Pmax | Maximum of V·I in the measured power quadrant. The maximum is solved analytically on every piecewise-linear segment. |
+| Vmp , Imp | Coordinates of the same piecewise-linear Pmax solution. |
+| FF | Pmax / (Isc ·Voc ). Withheld if Voc is unbracketed; out-of-range results are reported as errors, never clamped. |
+| Rs | \|dV/dI\| from a local multi-point linear fit near Voc . Withheld when Voc is unbracketed or the fit is degenerate. |
+| Rsh | \|dV/dI\| from a local multi-point linear fit near V = 0. |
+| η | Pmax / (G·A), with P in W, G in W/m², and illuminated area entered in cm². |
+
+Rs and Rsh are local light-sweep slope estimates, not a
+substitute for uncertainty-aware parameter fitting or dark-I-V analysis.
+
+## Validation
+
+The automated suite currently contains 53 tests, including:
+
+- 300 deterministic randomized linear curves checked against closed-form
+ Isc , Voc , Pmax , Vmp ,
+ Imp , and FF solutions.
+- Six continuous single-diode curves spanning nanoampere to ampere scales,
+ checked against an independent golden-section maximum-power oracle.
+- Current-scale invariance checks.
+- Censored sweeps, nonphysical curves, duplicate voltages, all-negative and
+ sparse sweeps.
+- Blank cells, duplicate/blank headers, malicious labels, quoted and malformed
+ CSV, input safety limits, and spreadsheet-formula neutralization.
+- Raw-data alignment, status/provenance export, and invalid efficiency inputs.
+
+Coverage gates apply to the scientific core: at least 90% statements, 80%
+branches, 90% functions, and 90% lines. CI additionally performs a high-severity
+dependency audit, both production builds, and a real-Chromium import,
+visualization, assistant, and CSV/XLSX download smoke test.
+
+See [`docs/VALIDATION.md`](docs/VALIDATION.md) for the audit register,
+tolerances, reproducibility commands, and residual limitations.
+
+## Input format
+
+Use `.xlsx` or `.csv`. Column A is voltage in volts. Each subsequent column is
+one signed current sweep in amperes, and row 1 contains channel labels.
+
+```csv
+Voltage (V),Focused Laser,-2 mm,+6 mm Focus
+0,1.539e-6,1.460e-6,1.583e-6
+0.05,1.528e-6,1.456e-6,1.565e-6
+2.50,-3.875e-6,-3.052e-6,-2.923e-6
```
-A ready-to-upload example lives in
-[`examples/sample_iv_data.csv`](examples/sample_iv_data.csv) (the same dataset
-the app loads by default).
+Rules:
-## Getting started
+- Every accepted channel must contain at least three unique voltage setpoints
+ with valid voltage-current pairs.
+- Blank or nonnumeric current cells are skipped and reported; they are never
+ converted to zero.
+- Exact duplicate voltage setpoints are averaged and flagged.
+- Blank and duplicate channel headers are assigned unique visible names.
+- Legacy `.xls` files are intentionally rejected; convert them to `.xlsx` or
+ CSV first.
-```bash
-npm install
-npm run dev # start the dev server (http://localhost:5173)
-npm test # run the physics unit tests
-npm run build # production build → dist/
-npm run build:standalone # single self-contained file → dist-standalone/index.html
-npm run build:all # both builds
-```
+The bundled example is
+[`examples/sample_iv_data.csv`](examples/sample_iv_data.csv).
-### Standalone file
+## Run and verify
-`npm run build:standalone` produces `dist-standalone/index.html` — a single file
-with all JavaScript and CSS inlined. Open it directly (`file://…`) with no server;
-it works offline (web fonts fall back to system fonts when there's no network).
+Node.js 22 is the CI reference runtime.
-## Deployment (Netlify)
+```bash
+npm ci
+npm run validate # dependency audit, coverage-gated tests, both builds
+npm run test:e2e # standalone build + real-browser smoke test
+npm run dev # local development server
+```
-This repo includes [`netlify.toml`](netlify.toml). To go live:
+Build targets:
-1. Push the repository to GitHub.
-2. In the Netlify dashboard, **Add new site → Import an existing project** and
- pick this repo.
-3. Netlify reads `netlify.toml` automatically (build `npm run build`, publish
- `dist`). No manual configuration needed.
+```bash
+npm run build # dist/
+npm run build:standalone # dist-standalone/index.html
+npm run build:all # both
+```
-Every push then redeploys. The continuous-integration workflow
-([`.github/workflows/ci.yml`](.github/workflows/ci.yml)) runs the unit tests and
-both builds, and uploads the standalone HTML as a downloadable artifact.
+The standalone file contains the application code and can run from `file://`
+without a backend. Browser profile and dataset storage is local and is not an
+authentication or access-control system.
-## Project structure
+## Project map
-```
+```text
src/
lib/
- ivAnalysis.js # parameter extraction + parsing + export helpers (pure)
- ivAnalysis.test.js # physics invariants & reference-value tests
- assistant.js # deterministic, offline dataset analyser
+ ivAnalysis.js
+ ivAnalysis.test.js
+ ivAnalysis.validation.test.js
+ assistant.js
components/
- ProfileGate.jsx # local operator gate (no passwords)
- Tour.jsx # guided walkthrough overlay
- Assistant.jsx # lab-assistant side panel
- shared.jsx # chart tooltip, channel toggles, lookup, raw-data table
- AboutPage.jsx
- App.jsx # main application
- theme.js icons.jsx persistence.js styles.css main.jsx
-examples/sample_iv_data.csv
-tests/e2e.smoke.mjs # optional browser smoke test (skips if no Chromium)
+ App.jsx
+docs/
+ VALIDATION.md
+examples/
+ sample_iv_data.csv
+tests/
+ e2e.smoke.mjs
+.github/workflows/
+ ci.yml
```
-## Testing
+## Standards context
+
+IEC 60904-1 defines measurement requirements for photovoltaic I-V
+characteristics; Solavin is an analysis and visualization layer, not an IEC
+conformity claim. NREL's photovoltaic measurement guidance likewise emphasizes
+calibration and uncertainty in the upstream measurement chain.
-- `npm test` — Vitest unit tests for the extraction math (run in CI).
-- `npm run test:e2e` — optional Playwright smoke test that builds the standalone
- bundle, drives it in a real browser, and verifies the app mounts cleanly with
- physical fill factors. Playwright is **not** a default dependency; install it
- first with `npm i -D playwright && npx playwright install chromium`. The test
- skips automatically (exit 0) if Playwright or a browser is unavailable, so it
- never blocks CI.
+- [IEC 60904-1:2020 — Photovoltaic devices, Part 1](https://webstore.iec.ch/en/publication/32004)
+- [NREL — Trust But Verify: Creating and Using Highly Accurate Measurements in Solar Research](https://www.nrel.gov/docs/fy05osti/36527.pdf)
-## License
+## License and citation
-[MIT](LICENSE) © 2026 John Myron Uy.
+[MIT](LICENSE) © 2026 John Myron Uy. Citation metadata is provided in
+[`CITATION.cff`](CITATION.cff).
diff --git a/docs/VALIDATION.md b/docs/VALIDATION.md
new file mode 100644
index 0000000..001ff0e
--- /dev/null
+++ b/docs/VALIDATION.md
@@ -0,0 +1,141 @@
+# Solavin 4.0 validation and audit record
+
+**Validation date:** 2026-07-29
+**Reference runtime:** Node.js 22
+**Scientific method identifier:** `piecewise-linear-v4`
+**Audited baseline:** `375fa05129a5b1fdb8364f50dda3029db9001738`
+
+## Scope and claim
+
+This record covers the software path from an uploaded array of voltage-current
+cells through parsing, parameter extraction, visualization data, and exported
+results. It supports confidence that Solavin applies its documented
+piecewise-linear method consistently.
+
+It does not establish metrological traceability, quantify measurement
+uncertainty, validate an upstream instrument, or certify a procedure against
+IEC 60904-1. Those require calibrated equipment, a documented measurement
+protocol, environmental controls, and uncertainty analysis outside this
+browser application.
+
+No serious scientific tool can truthfully promise to be “flawless.” The
+defensible claim is narrower: the algorithms below are explicit, their failure
+states are visible, and a repeatable automated suite guards the tested scope.
+
+## Audit findings and remediation
+
+The baseline dependency scan reported nine known vulnerabilities: one critical,
+three high, and five moderate. After replacing the workbook dependency and
+upgrading the build/test/chart stack, `npm audit` reported zero known
+vulnerabilities on the validation date.
+
+| Severity | Original finding | Scientific or operational risk | Remediation |
+|---|---|---|---|
+| Critical | Missing current cells were coerced to zero. | Fabricated points changed curve shape and derived metrics. | Missing/nonnumeric cells are skipped and surfaced as import warnings. |
+| Critical | Channels were combined by array index. | A gap in one channel shifted later currents onto incorrect voltages. | Visualization and raw export now use a union keyed by numeric voltage. |
+| High | Charts used smoothed `monotone` curves while calculations used linear segments. | The visual could imply unmeasured extrema or curvature. | All I-V/P-V lines use straight measured segments. |
+| High | Unbracketed Voc was presented as an exact endpoint. | FF and Rs appeared valid despite a censored sweep. | Voc becomes a lower bound; Pmax is provisional; FF and Rs are withheld. |
+| High | Blank headers changed channel-column mapping. | Measurements could be assigned to the wrong condition. | Physical column positions are retained; blank and duplicate labels are uniquely named. |
+| High | The Excel dependency and old build/test packages had known vulnerabilities. | Untrusted-workbook and build-chain exposure. | Replaced `xlsx`, upgraded Vite/Vitest/Recharts, and reached `npm audit` zero known vulnerabilities at validation time. |
+| Medium | The workflow filename was `.ciyml` inside `.github/workflows`. | GitHub Actions did not recognize the intended CI workflow. | Installed a valid `.github/workflows/ci.yml` with audit, coverage, build, Chromium, and artifact gates. |
+| Medium | Comparison charts hard-coded nanowatts. | Ampere-scale and other datasets were mislabeled. | Shared automatic SI scaling is used throughout. |
+| Medium | CSV string cells could begin spreadsheet formulas. | Opening an export could execute an injected formula in spreadsheet software. | Formula-leading strings are prefixed before CSV serialization. |
+| Medium | The interface implied a connected SMU and four-wire mode. | Researchers could mistake a visualization-only tool for instrument control. | UI now states `LOCAL / NO BACKEND` and makes no wiring/instrument claim. |
+| Medium | Endpoint two-point resistance estimates were fragile. | Rs /Rsh varied strongly with one noisy sample. | Local multi-point regressions now return fit diagnostics and withhold degenerate estimates. |
+
+## Accuracy oracles
+
+### Closed-form linear curves
+
+For
+
+`I(V) = Isc × (1 − V/Voc)`
+
+the suite checks 300 seeded randomized curves spanning 10⁻⁸ A to 1 A and
+0.15 V to 5 V. It independently expects:
+
+- Vmp = Voc /2
+- Imp = Isc /2
+- Pmax = Isc Voc /4
+- FF = 0.25
+
+Samples are shuffled and irregularly spaced so success does not depend on input
+ordering or a fixed grid.
+
+### Continuous single-diode curves
+
+Six ideal single-diode cases span 8 nA to 4.2 A, Voc values from
+0.42 V to 2.08 V, and ideality factors from 1.0 to 2.0. A golden-section search
+evaluates the continuous source equation independently of Solavin. The sampled
+piecewise-linear extraction must meet:
+
+| Output | Acceptance tolerance |
+|---|---:|
+| Isc relative error | < 1×10⁻¹⁰ |
+| Voc relative error | < 2×10⁻⁵ |
+| Vmp absolute error | < 2 sample steps |
+| Pmax relative error | < 2×10⁻⁴ |
+| FF relative error | < 2×10⁻⁴ |
+
+These tolerances validate the sampled piecewise-linear method. They are not a
+claim about an instrument's measurement accuracy.
+
+## Data-integrity controls
+
+- Only finite numeric voltage-current pairs enter extraction.
+- Signed current is preserved; absolute current is never used for physics.
+- Exact duplicate voltage values are averaged deterministically and counted.
+- Sparse channels retain blank gaps and are aligned by voltage.
+- Pmax is restricted to measured V ≥ 0, I ≥ 0 segments.
+- Voc requires a measured nonnegative positive-to-negative crossing.
+- Multiple nonnegative positive-to-negative crossings are ambiguous and
+ withhold Voc , FF, and Rs .
+- FF outside the physical 0–100% range is an error, not a clamped result.
+- Efficiency rejects nonfinite, negative-power, zero-area, and
+ zero-irradiance inputs.
+- Every metrics row carries method version, sample counts, statuses, quality,
+ source, import flags, metric flags, and any efficiency inputs.
+- XLSX exports preserve signed raw data and metadata in separate sheets.
+
+## Reproduction
+
+From a clean checkout:
+
+```bash
+npm ci
+npm audit --audit-level=high
+npm run test:coverage
+npm run build:all
+npx playwright install --with-deps chromium
+CI=1 node tests/e2e.smoke.mjs
+```
+
+Expected automated gates:
+
+- all Vitest tests pass;
+- scientific-core coverage ≥90% statements, ≥80% branches, ≥90% functions,
+ and ≥90% lines;
+- dependency audit has no high/critical finding;
+- both standard and standalone Vite builds succeed;
+- Chromium imports a sparse CSV, renders finite chart paths, exercises the
+ assistant and efficiency calculator, and downloads CSV and XLSX outputs.
+
+## Residual limitations
+
+| Limitation | Consequence | Required research control |
+|---|---|---|
+| No uncertainty propagation | Values do not include confidence intervals. | Retain instrument uncertainty and propagate it externally. |
+| No spectral or temperature correction | Results from differing conditions may not be directly comparable. | Record and normalize irradiance, spectrum, and device temperature under the chosen protocol. |
+| No hysteresis/sweep-rate model | Direction- or timing-dependent devices may appear deceptively stable. | Preserve forward/reverse sweeps and acquisition timing as separate channels and metadata. |
+| Rs /Rsh are local slopes | They are not equivalent to a full diode-model parameter fit. | Use dark/light model fitting with uncertainty when those parameters drive conclusions. |
+| Exact-voltage duplicate averaging | Repeated setpoints are collapsed without time-order analysis. | Analyze time series separately when drift or hysteresis matters. |
+| Browser-local persistence | It is not a controlled laboratory information system. | Archive raw files and exported results in a versioned research repository. |
+| No instrument connection | Solavin cannot enforce acquisition settings or calibration. | Record instrument model, calibration, wiring, ranges, dwell time, and compliance separately. |
+
+## Standards context
+
+- [IEC 60904-1:2020](https://webstore.iec.ch/en/publication/32004)
+ specifies photovoltaic I-V measurement requirements.
+- [NREL, Trust But Verify](https://www.nrel.gov/docs/fy05osti/36527.pdf)
+ discusses calibration, uncertainty, and common photovoltaic measurement
+ errors.
diff --git a/index.html b/index.html
index 94b1ab6..6117a13 100644
--- a/index.html
+++ b/index.html
@@ -6,7 +6,7 @@
Solavin — Photovoltaic Characterization Suite
Solavin
-
v3.1.0
+
v4.0.0
}
{sideOpen &&
- ONLINE SMU-2400
+ LOCAL NO BACKEND
}
{sideOpen && NAVIGATION
}
@@ -329,7 +405,7 @@ export default function App() {
{/* Filled gradient treatment so the assistant reads as a primary
feature in the rail, not a muted afterthought. */}
- setChatOpen(!chatOpen)} className="press" style={{ display: "flex", alignItems: "center", gap: 9, width: "100%", padding: sideOpen ? "10px 12px" : "10px 0", borderRadius: 8, border: "none", background: "linear-gradient(135deg," + t.accent + "," + t.accent2 + ")", color: "#fff", fontSize: 11.5, fontWeight: 700, justifyContent: sideOpen ? "flex-start" : "center", boxShadow: chatOpen ? "0 0 0 1px " + t.accent + "55 inset" : "0 4px 16px " + t.accentG }}>Lab Assistant }{sideOpen && AI }
+ setChatOpen(!chatOpen)} className="press" style={{ display: "flex", alignItems: "center", gap: 9, width: "100%", padding: sideOpen ? "10px 12px" : "10px 0", borderRadius: 8, border: "none", background: "linear-gradient(135deg," + t.accent + "," + t.accent2 + ")", color: "#fff", fontSize: 11.5, fontWeight: 700, justifyContent: sideOpen ? "flex-start" : "center", boxShadow: chatOpen ? "0 0 0 1px " + t.accent + "55 inset" : "0 4px 16px " + t.accentG }}>Lab Assistant }{sideOpen && LOCAL }
setSideOpen(!sideOpen)} className="mono" style={{ borderTop: "1px solid " + t.border, background: "none", border: "none", padding: "9px 10px", color: t.textD, display: "flex", alignItems: "center", justifyContent: sideOpen ? "space-between" : "center", gap: 5, fontSize: 9, width: "100%", letterSpacing: ".1em" }}>{sideOpen && COLLAPSE }
@@ -374,28 +450,43 @@ export default function App() {
SESSION ▸ {new Date().toISOString().slice(0, 10)}
Measurement Dashboard
-
{ds.name} · {ds.conditions.length} conditions · {(ds.ivData[ds.conditions[0]] || []).length} sweep points per channel
+
{ds.name} · {ds.conditions.length} conditions · {Math.min(...ds.conditions.map((c) => (ds.ivData[c] || []).length))}–{Math.max(...ds.conditions.map((c) => (ds.ivData[c] || []).length))} valid points/channel
-
-
f.c + ": " + f.w).join("\n") : "All channels passed automated sanity checks"} style={{ padding: "6px 12px", borderRadius: 6, background: t.card, border: "1px solid " + t.border, cursor: qualityFlags.length ? "help" : "default" }}>
DATA QUALITY
{qualityFlags.length ? "⚠ " + qualityFlags.length + " FLAG" + (qualityFlags.length > 1 ? "S" : "") : <>
+
CONVENTION
GENERATOR · SIGNED I
+
f.c + ": " + f.w).join("\n") : "All automated checks passed"} style={{ padding: "6px 12px", borderRadius: 6, background: t.card, border: "1px solid " + t.border, cursor: qualityFlags.length ? "help" : "default" }}>
AUTOMATED CHECKS
f.severity === "error") ? t.danger : qualityFlags.length ? t.warn : t.success, fontWeight: 600, marginTop: 2, display: "flex", alignItems: "center", gap: 4 }}>{qualityFlags.length ? "⚠ " + qualityFlags.length + " FLAG" + (qualityFlags.length > 1 ? "S" : "") : <>
{(() => {
- const vals = Object.values(allM).filter(Boolean);
- const bp = Math.max(0, ...vals.map((m) => m.pmax));
- const bi = Math.max(0, ...vals.map((m) => m.isc));
- const bv = Math.max(0, ...vals.map((m) => m.voc));
- const bf = Math.max(0, ...vals.map((m) => m.ff));
- const bestOf = (key) => { let bc = "", bw = -Infinity; ds.conditions.forEach((c) => { const m = allM[c]; if (m && m[key] > bw) { bw = m[key]; bc = c; } }); return bc; };
+ const eligible = (m, key) => {
+ if (!m || m.quality === "invalid" || !Number.isFinite(m[key])) return false;
+ if (key === "voc") return m.status?.voc === "measured" || m.status?.voc === "interpolated";
+ if (key === "pmax") return m.status?.pmax === "measured" || m.status?.pmax === "interpolated";
+ if (key === "ff") return m.status?.ff === "computed";
+ return true;
+ };
+ const bestOf = (key) => {
+ let best = null;
+ ds.conditions.forEach((condition) => {
+ const metrics = allM[condition];
+ if (eligible(metrics, key) && (!best || metrics[key] > best.value)) {
+ best = { condition, value: metrics[key] };
+ }
+ });
+ return best;
+ };
+ const bp = bestOf("pmax");
+ const bi = bestOf("isc");
+ const bv = bestOf("voc");
+ const bf = bestOf("ff");
return [
- { l: "P_max", sub: "Maximum power", v: bp / scales.p.div, d: 3, unit: pU, c: dark ? "#fbbf24" : "#b45309", IC: Ic.Up, best: bestOf("pmax") },
- { l: "I_sc", sub: "Short-circuit current", v: bi / scales.i.div, d: 3, unit: iU, c: dark ? "#22d3ee" : "#0891b2", IC: Ic.Act, best: bestOf("isc") },
- { l: "V_oc", sub: "Open-circuit voltage", v: bv, d: 3, unit: "V", c: dark ? "#38bdf8" : "#0284c7", IC: Ic.Target, best: bestOf("voc") },
- { l: "FF", sub: "Fill factor", v: bf * 100, d: 1, unit: "%", c: dark ? "#a78bfa" : "#7c3aed", IC: Ic.Rad, best: bestOf("ff") },
+ { l: "P_max", sub: "Maximum power", v: bp ? bp.value / scales.p.div : NaN, d: 3, unit: pU, c: dark ? "#fbbf24" : "#b45309", IC: Ic.Up, best: bp?.condition },
+ { l: "I_sc", sub: "Short-circuit current", v: bi ? bi.value / scales.i.div : NaN, d: 3, unit: iU, c: dark ? "#22d3ee" : "#0891b2", IC: Ic.Act, best: bi?.condition },
+ { l: "V_oc", sub: "Open-circuit voltage", v: bv ? bv.value : NaN, d: 3, unit: "V", c: dark ? "#38bdf8" : "#0284c7", IC: Ic.Target, best: bv?.condition },
+ { l: "FF", sub: "Fill factor", v: bf ? bf.value * 100 : NaN, d: 1, unit: "%", c: dark ? "#a78bfa" : "#7c3aed", IC: Ic.Rad, best: bf?.condition },
].map((s, i) => (
@@ -411,7 +502,7 @@ export default function App() {
{s.unit}
- {s.best}
+ {s.best || "No valid channel"}
{C8.map((col, i) =>
+Number(v).toFixed(2)} tick={{ fill: t.textM, fontSize: 9 }} label={{ value: "POWER (" + pU + ")", angle: -90, position: "insideLeft", offset: 0, fill: t.textD, fontSize: 8, letterSpacing: "0.18em", style: { textAnchor: "middle" } }} stroke={t.borderS} />
{C8.map((col, i) =>
@@ -525,8 +616,8 @@ export default function App() {
+Number(v).toFixed(2)} tick={{ fill: t.textM, fontSize: 9 }} label={{ value: "P (" + pU + ")", angle: -90, position: "insideLeft", offset: 8, fill: t.textD, fontSize: 8, letterSpacing: "0.14em", style: { textAnchor: "middle" } }} stroke={t.borderS} />
Performance Profile NORMALIZED
-
0 → 100% RELATIVE
+
{radarConds.length} COMPLETE CHANNEL{radarConds.length === 1 ? "" : "S"} · 0 → 100% RELATIVE
- No active channel has complete reportable Isc, Voc, Pmax, and FF values.
}
+ }
{vizTab === "compare" && (() => {
- const bd = activeConds.map((c) => { const m = allM[c]; if (!m) return null; return { name: c, Pmax: m.pmax * 1e9, color: C8[ds.conditions.indexOf(c) % C8.length] }; }).filter(Boolean).sort((a, b) => b.Pmax - a.Pmax);
+ const bd = activeConds.map((c) => {
+ const m = allM[c];
+ if (!m || m.quality === "invalid" || !["measured", "interpolated"].includes(m.status?.pmax)) return null;
+ return { name: c, Pmax: m.pmax / scales.p.div, color: C8[ds.conditions.indexOf(c) % C8.length] };
+ }).filter(Boolean).sort((a, b) => b.Pmax - a.Pmax);
return
P_max Comparison
-
RANKED · DESC
+
VALID CHANNELS · DESC
-
{bd.map((e, i) => | )}
+
{bd.map((e, i) => | )} ;
})()}
}
@@ -565,10 +663,11 @@ export default function App() {
{efficiency && Object.values(efficiency).some((e) => e > 100) && η exceeds 100 %, which is unphysical — check that cell area is in cm² and irradiance in W/m².
}
+ {exportError && {exportError}
}
{qualityFlags.length > 0 &&
⚠ DATA QUALITY · {qualityFlags.length} FLAG{qualityFlags.length > 1 ? "S" : ""}
- {qualityFlags.map((f, i) =>
{f.c} {f.w}
)}
+ {qualityFlags.map((f, i) =>
{f.severity === "error" ? "ERROR · " : ""}{f.c} {f.w}
)}
}
@@ -581,19 +680,19 @@ export default function App() {
{["CONDITION", "I_SC (" + iU + ")", "V_OC (V)", "P_MAX (" + pU + ")", "FF (%)", "R_S", "R_SH"].concat(efficiency ? ["η (%)"] : []).map((h) => {h} )} {ds.conditions.map((c, ci) => { const m = allM[c]; if (!m) return null; const col = C8[ci % C8.length]; const colTxt = (t.chan || C8)[ci % (t.chan || C8).length]; return (
- ⚠ }{(m.isc / scales.i.div).toFixed(3)}
- {m.voc.toFixed(3)}{m.notes.vocBeyondRange ? "*" : ""}
- {(m.pmax / scales.p.div).toFixed(3)}
- 0.5 ? "linear-gradient(90deg,#16a34a,#22c55e)" : m.ff > 0.3 ? "linear-gradient(90deg,#d97706,#f59e0b)" : "linear-gradient(90deg,#dc2626,#f43f5e)", transition: "width .6s ease" }} />
{(m.ff * 100).toFixed(1)} {fmtSI(m.rs, "Ω", 2)}
- {m.rsh === Infinity ? "∞" : fmtSI(m.rsh, "Ω", 2)}
+ ⚠ }{Number.isFinite(m.isc) ? (m.isc / scales.i.div).toFixed(3) : "—"}
+ {m.voc == null ? "—" : (m.notes.vocBeyondRange ? "≥" : "") + m.voc.toFixed(3)}
+ {["measured", "interpolated", "provisional"].includes(m.status?.pmax) ? (m.pmax / scales.p.div).toFixed(3) + (m.status?.pmax === "provisional" ? "*" : "") : "—"}
+ {m.ff == null ? — : 0.5 ? "linear-gradient(90deg,#16a34a,#22c55e)" : m.ff > 0.3 ? "linear-gradient(90deg,#d97706,#f59e0b)" : "linear-gradient(90deg,#dc2626,#f43f5e)", transition: "width .6s ease" }} />
{(m.ff * 100).toFixed(1)} }
+ {m.rs == null ? "—" : fmtSI(m.rs, "Ω", 2)}
+ {m.rsh == null ? "—" : m.rsh === Infinity ? "∞" : fmtSI(m.rsh, "Ω", 2)}
{efficiency && {efficiency[c] != null ? efficiency[c].toPrecision(3) : "-"} }
); })}
- {Object.values(allM).some((m) => m && m.notes.vocBeyondRange) &&
* V_oc lies beyond the measured sweep range — value shown is the last sweep voltage.
}
+ {Object.values(allM).some((m) => m && (m.notes.vocBeyondRange || m.status?.pmax === "provisional")) &&
* Sweep does not bracket V_oc: V_oc is a lower bound, P_max is provisional, and FF/R_s are withheld.
}
}
@@ -602,17 +701,17 @@ export default function App() {
04 / DATA INGEST
Import Measurement Data
-
Drop a workbook with voltage in column A and current sweeps in subsequent columns. Sheet headers become channel labels.
+
Drop an .xlsx workbook or RFC 4180 CSV with voltage in column A and signed current sweeps in subsequent columns. Sheet headers become channel labels.
{ e.preventDefault(); setDragOver(true); }} onDragLeave={() => setDragOver(false)} onDrop={(e) => { e.preventDefault(); setDragOver(false); if (e.dataTransfer && e.dataTransfer.files && e.dataTransfer.files[0]) handleFile(e.dataTransfer.files[0]); }} onClick={() => { if (fileRef.current) fileRef.current.click(); }} className="corners" style={{ border: "1.5px dashed " + (dragOver ? t.accent : t.border), borderRadius: 14, padding: "50px 28px", textAlign: "center", background: dragOver ? "linear-gradient(135deg," + t.accent + "14," + t.accent2 + "08)" : "linear-gradient(180deg," + t.card + "," + t.cardAlt + ")", maxWidth: 560, margin: "0 auto", transition: "all .25s", position: "relative", overflow: "hidden", cursor: "pointer" }}>
-
{dragOver ? "Release to upload" : "Drop Excel or CSV here"}
-
or click to browse · supports .xlsx, .xls, .csv
+
{dragOver ? "Release to upload" : "Drop XLSX or CSV here"}
+
or click to browse · .xlsx / .csv · 25 MB maximum
-
{ if (e.target.files && e.target.files[0]) handleFile(e.target.files[0]); }} />
+
{ if (e.target.files && e.target.files[0]) handleFile(e.target.files[0]); e.target.value = ""; }} />
- FORMAT · COL A = V, COL B+ = I · UNITS · VOLTS / AMPS
+ FORMAT · COL A = V, COL B+ = SIGNED I · UNITS · VOLTS / AMPS
⚠ {importError}
}
@@ -636,10 +735,10 @@ export default function App() {
{page === "about" &&
- ISC · VOC · PMAX · FF · η — v3.1.0
+ ISC · VOC · PMAX · FF · η — v4.0.0
@@ -649,7 +748,7 @@ export default function App() {
{tourStep >= 0 && setTourStep(tourStep + 1)} onBack={() => { if (tourStep > 0) setTourStep(tourStep - 1); }} onSkip={dismissTour} onNav={setPage} onVizTab={setVizTab} onChat={() => setChatOpen(true)} onCloseChat={() => setChatOpen(false)} />}
- {sheetPicker && Select Sheet
{sheetPicker.valid.map((s) =>
doLoad(sheetPicker.file.name, sheetPicker.sheets, s)} style={{ display: "block", width: "100%", padding: "9px 13px", marginBottom: 4, borderRadius: 8, border: "1px solid " + t.border, background: t.inputBg, color: t.text, fontSize: 11, textAlign: "left" }}>{s} )}
setSheetPicker(null)} style={{ marginTop: 6, background: "none", border: "none", color: t.textM, fontSize: 10 }}>Cancel Select Sheet
{sheetPicker.valid.map((s) =>
doLoad(sheetPicker.fileName, sheetPicker.sheets, s)} style={{ display: "block", width: "100%", padding: "9px 13px", marginBottom: 4, borderRadius: 8, border: "1px solid " + t.border, background: t.inputBg, color: t.text, fontSize: 11, textAlign: "left" }}>{s} )}
setSheetPicker(null)} style={{ marginTop: 6, background: "none", border: "none", color: t.textM, fontSize: 10 }}>Cancel
Solavin processes current-voltage data from photovoltaic cells to extract standard figures of merit for research characterization.
-
1. Data ingestion — upload .xlsx/.csv with voltage in column A and one current sweep per following column.
+
1. Data ingestion — upload .xlsx/.csv with voltage in column A and one signed-current sweep per following column. Blank cells are skipped and reported, never replaced with zeros.
2. Parameter extraction — Isc (current at V=0), Voc (the I=0 crossing), Pmax/Vmp/Imp in the power quadrant, FF = Pmax/(Isc·Voc), and slope-based Rs & Rsh.
3. Efficiency — cell area and irradiance inputs give η = Pmax/(G·A).
4. Visualization — I-V, P-V, radar, and comparative charts with MPP overlays and zoom.
-
5. Export — one-click CSV/Excel export of all metrics.
+
5. Export — CSV metrics plus a three-sheet Excel workbook containing metrics, signed raw data, and analysis metadata/provenance.
Accuracy & conventions
-
Extraction operates on signed current (generator convention): positive in the power quadrant, negative beyond Voc. The maximum-power search is restricted to V≥0, I≥0, so fill factor is always physical (< 100%).
-
Isc and Voc are linearly interpolated between the two samples that bracket V = 0 and I = 0 — never nearest-neighbour. The maximum-power point is located on the piecewise-linear P-V curve itself, including between measured samples, so Pmax does not snap to the voltage grid. Automated sanity checks flag non-positive Isc, non-monotonic sweeps and sparse sampling.
-
The core math is validated against single-diode reference silicon cells (FF ≈ 0.83 at STC) by an automated test suite that runs on every build, so results stay reproducible.
+
Extraction operates on signed current (generator convention): positive in the power quadrant, negative beyond Voc. Plots and calculations both use piecewise-linear interpolation, so smoothing cannot invent unmeasured extrema.
+
Isc and Voc are linearly interpolated between samples that bracket V = 0 and I = 0. The maximum-power point is solved exactly on each piecewise-linear segment. If the sweep does not bracket Voc, Solavin reports only a lower bound, marks Pmax provisional, and withholds FF and Rs rather than manufacturing precise-looking values.
+
The core is tested against analytic linear curves, independent high-resolution single-diode oracles, scale invariants, sparse workbooks, malformed input, and deterministic randomized sweeps. Every export includes status and quality columns so caveats travel with the numbers.
+
Solavin validates analysis, not the measurement setup. Calibration, spectral mismatch, device temperature, irradiance uniformity, sweep direction/rate, and measurement uncertainty remain the operator's responsibility. Rs and Rsh are explicitly local slope estimates from one light sweep.
Technology
Frontend: React 18 + Vite
-
Charts: Recharts
-
Excel: SheetJS
-
Tests: Vitest
+
Charts: Recharts · linear interpolation
+
Excel: isolated XLSX reader/writer
+
Tests: Vitest + Playwright
diff --git a/src/components/ProfileGate.jsx b/src/components/ProfileGate.jsx
index a22c23b..0567e13 100644
--- a/src/components/ProfileGate.jsx
+++ b/src/components/ProfileGate.jsx
@@ -49,7 +49,7 @@ export function ProfileGate(props) {
{/* Fixed top nav (above the hero layer so its buttons stay clickable) */}
@@ -59,7 +59,7 @@ export function ProfileGate(props) {
Solavin
-
GitHub ↗
+
GitHub ↗
props.onEnter({ id: "guest", name: "Guest", isGuest: true })} className="press" style={{ padding: "11px 22px", borderRadius: 10, border: "1px solid rgba(255,255,255,.22)", background: GRAD, color: "#04140d", fontSize: 13, fontWeight: 800, letterSpacing: ".01em", boxShadow: "0 8px 24px rgba(34,211,238,.4)", display: "inline-flex", alignItems: "center", gap: 8, animation: "glowPulse 2.2s ease-in-out infinite" }}>→
v3 · ACCURACY-VERIFIED EXTRACTION
+ v4 · STATUS-AWARE ANALYSIS
Photovoltaic I-V data, SAMPLE · ROOM LIGHTS
- ● LIVE
+ ● SAMPLE
@@ -127,9 +127,9 @@ export function ProfileGate(props) {
- {/* bottom instrument strip */}
+ {/* bottom application-status strip */}
- SMU-2400 · CALIBRATED
+ LOCAL ANALYSIS · NO INSTRUMENT LINK
Solavin · PV CHARACTERIZATION SUITE
diff --git a/src/components/Tour.jsx b/src/components/Tour.jsx
index 69745a9..fd1496b 100644
--- a/src/components/Tour.jsx
+++ b/src/components/Tour.jsx
@@ -100,7 +100,7 @@ export function TourOverlay(p) {
GUIDED WALKTHROUGH
- SKIP ✕
+ SKIP ✕
{step.title}
{step.desc}
diff --git a/src/components/Welcome.jsx b/src/components/Welcome.jsx
index 2fe7345..3c1c121 100644
--- a/src/components/Welcome.jsx
+++ b/src/components/Welcome.jsx
@@ -118,7 +118,7 @@ export function Welcome({ t, onClose, onStartTour }) {
WHAT YOU PROVIDE
- An .xlsx, .xls or .csv workbook — one voltage column, any number of current sweeps. Header row becomes channel labels.
+ An .xlsx or .csv workbook — one voltage column, any number of signed-current sweeps. Header row becomes channel labels; legacy .xls is intentionally rejected.
{["COL", "CONTENT", "UNIT"].map((h) => {h} )} {result.map((r, i) => (
{(r.current / iSc.div).toFixed(4)}
+ {Number.isFinite(r.current) ? (r.current / iSc.div).toFixed(4) : "—"}
{r.source.toUpperCase()}
))}
@@ -174,7 +182,7 @@ export function RawDataViewer(p) {
if (!ds) return null;
const allCols = ["voltage"].concat(ds.conditions);
- const rows = ds.ivData[ds.conditions[0]] || [];
+ const rows = buildAlignedRows(ds, ds.conditions);
function doSearch() {
setWarning(""); setMatchIdx(-1);
@@ -192,14 +200,19 @@ export function RawDataViewer(p) {
setMatchIdx(bestI);
} else {
if (isNaN(num)) { setWarning("Enter a numeric current value (in Amps, e.g. 1.5e-6)."); return; }
- const pts = ds.ivData[searchCol];
- if (!pts || pts.length === 0) { setWarning('No data for condition "' + searchCol + '".'); return; }
- let bestI = 0, bestD = Math.abs(pts[0].rawCurrent - num);
- for (let i = 1; i < pts.length; i++) { const d = Math.abs(pts[i].rawCurrent - num); if (d < bestD) { bestD = d; bestI = i; } }
- const relErr = pts[bestI].rawCurrent !== 0 ? bestD / Math.abs(pts[bestI].rawCurrent) : bestD;
- if (relErr > 0.1) setWarning("No close match found. Nearest is " + pts[bestI].rawCurrent.toExponential(3) + " A at V = " + pts[bestI].voltage.toFixed(3) + "V.");
- else if (bestD > 0) setWarning("Nearest match: " + pts[bestI].rawCurrent.toExponential(3) + " A at V = " + pts[bestI].voltage.toFixed(3) + "V.");
- setMatchIdx(bestI);
+ const candidates = rows
+ .map((row, index) => ({ index, voltage: row.voltage, current: row[searchCol] }))
+ .filter((entry) => Number.isFinite(entry.current));
+ if (!candidates.length) { setWarning('No data for condition "' + searchCol + '".'); return; }
+ let best = candidates[0], bestD = Math.abs(candidates[0].current - num);
+ for (let i = 1; i < candidates.length; i++) {
+ const d = Math.abs(candidates[i].current - num);
+ if (d < bestD) { bestD = d; best = candidates[i]; }
+ }
+ const relErr = best.current !== 0 ? bestD / Math.abs(best.current) : bestD;
+ if (relErr > 0.1) setWarning("No close match found. Nearest is " + best.current.toExponential(3) + " A at V = " + best.voltage.toFixed(3) + "V.");
+ else if (bestD > 0) setWarning("Nearest match: " + best.current.toExponential(3) + " A at V = " + best.voltage.toFixed(3) + "V.");
+ setMatchIdx(best.index);
}
}
const isErr = (w) => w.indexOf("outside") !== -1 || w.indexOf("No close") !== -1 || w.indexOf("not found") !== -1;
@@ -226,7 +239,7 @@ export function RawDataViewer(p) {
)}
{ const st = e.currentTarget.scrollTop; setScrollTop((prev) => (Math.abs(prev - st) >= ROW_H ? st : prev)); }} style={{ maxHeight: 220, overflow: "auto" }}>
-
+
{allCols.map((h, i) => { const isSearched = h === (searchCol === "voltage" ? "voltage" : searchCol); return {i === 0 ? "V (V)" : h} ; })} {(() => {
// Virtual window: render only ~15 visible rows plus overscan;
@@ -241,7 +254,7 @@ export function RawDataViewer(p) {
out.push(
{row.voltage.toFixed(2)}
- {ds.conditions.map((c, ci) => { const pt = ds.ivData[c][ri]; return {pt ? pt.rawCurrent.toExponential(3) : "-"} ; })}
+ {ds.conditions.map((c, ci) => { const value = row[c]; return {Number.isFinite(value) ? value.toExponential(3) : "—"} ; })}
);
}
diff --git a/src/lib/assistant.js b/src/lib/assistant.js
index 7f87e99..4b17259 100644
--- a/src/lib/assistant.js
+++ b/src/lib/assistant.js
@@ -14,34 +14,43 @@ import { fmtSI } from "./ivAnalysis.js";
// cell scale (µA lab devices through A-scale production cells).
const fmt = {
isc: (m) => fmtSI(m.isc, "A"),
- voc: (m) => m.voc.toFixed(3) + " V",
- pmax: (m) => fmtSI(m.pmax, "W"),
- ff: (m) => (m.ff * 100).toFixed(1) + " %",
- rs: (m) => fmtSI(m.rs, "Ω", 2),
- rsh: (m) => (m.rsh === Infinity ? "∞" : fmtSI(m.rsh, "Ω", 2)),
+ voc: (m) => m.voc == null ? "unavailable" : `${m.status?.voc === "lower-bound" ? "≥ " : ""}${m.voc.toFixed(3)} V`,
+ pmax: (m) => `${fmtSI(m.pmax, "W")}${m.status?.pmax === "provisional" ? " (provisional)" : ""}`,
+ ff: (m) => Number.isFinite(m.ff) ? (m.ff * 100).toFixed(1) + " %" : "withheld",
+ rs: (m) => m.rs == null ? "withheld" : fmtSI(m.rs, "Ω", 2),
+ rsh: (m) => m.rsh == null ? "withheld" : (m.rsh === Infinity ? "∞" : fmtSI(m.rsh, "Ω", 2)),
};
+function reportable(m, key) {
+ if (!m || m.quality === "invalid" || !Number.isFinite(m[key])) return false;
+ if (key === "voc") return m.status?.voc === "measured" || m.status?.voc === "interpolated";
+ if (key === "pmax") return m.status?.pmax === "measured" || m.status?.pmax === "interpolated";
+ if (key === "ff") return m.status?.ff === "computed";
+ if (key === "isc") return m.status?.isc !== "unavailable";
+ return true;
+}
+
function rankBy(dataset, allMetrics, key) {
return dataset.conditions
.map((c) => ({ c, m: allMetrics[c] }))
- .filter((x) => x.m)
+ .filter((x) => reportable(x.m, key))
.sort((a, b) => b.m[key] - a.m[key]);
}
function summarize(dataset, allMetrics) {
+ const lines = dataset.conditions.map((c) => {
+ const m = allMetrics[c];
+ if (!m) return `• ${c}: insufficient valid samples`;
+ if (m.quality === "invalid")
+ return `• ${c} [INVALID]: metrics are not reportable; inspect the channel's data-quality errors`;
+ const flag = m.quality === "pass" ? "" : ` [${m.quality.toUpperCase()}]`;
+ return `• ${c}${flag}: Pmax ${fmt.pmax(m)}, Isc ${fmt.isc(m)}, Voc ${fmt.voc(m)}, FF ${fmt.ff(m)}`;
+ });
const ranked = rankBy(dataset, allMetrics, "pmax");
- if (!ranked.length) return "No metrics available for the active dataset.";
- const best = ranked[0];
- const worst = ranked[ranked.length - 1];
- const lines = ranked.map(
- ({ c, m }) => `• ${c}: Pmax ${fmt.pmax(m)}, Isc ${fmt.isc(m)}, Voc ${fmt.voc(m)}, FF ${fmt.ff(m)}`
- );
- return (
- `Summary — ${dataset.name}\n\n` +
- lines.join("\n") +
- `\n\nHighest Pmax: ${best.c} (${fmt.pmax(best.m)}).` +
- `\nLowest Pmax: ${worst.c} (${fmt.pmax(worst.m)}).`
- );
+ const ranking = ranked.length
+ ? `\n\nHighest reportable Pmax: ${ranked[0].c} (${fmt.pmax(ranked[0].m)}).`
+ : "\n\nNo channel has a reportable Pmax; review the data-quality flags.";
+ return `Summary — ${dataset.name}\n\n${lines.join("\n")}${ranking}`;
}
function compare(dataset, allMetrics) {
@@ -57,7 +66,7 @@ function compare(dataset, allMetrics) {
function fillFactor(dataset, allMetrics) {
const ranked = rankBy(dataset, allMetrics, "ff");
- if (!ranked.length) return "No fill-factor data available.";
+ if (!ranked.length) return "No reportable fill-factor values are available. Solavin withholds FF when Voc is not bracketed or a channel fails physical checks.";
const vals = ranked.map((x) => x.m.ff * 100);
const lo = Math.min(...vals).toFixed(1);
const hi = Math.max(...vals).toFixed(1);
@@ -66,16 +75,19 @@ function fillFactor(dataset, allMetrics) {
`Fill factor measures how "square" the I-V curve is:\n` +
`FF = Pmax / (Isc · Voc).\n\n` +
`This dataset ranges ${lo}–${hi} %. Best: ${best.c} at ${fmt.ff(best.m)}.\n\n` +
- `Values in this range are typical for cells measured below standard ` +
- `illumination and/or with appreciable series resistance — both push the ` +
- `knee of the curve inward. Crystalline silicon at STC typically reaches ` +
- `70–82 %.`
+ `Interpret FF in the context of device technology, illumination, temperature, ` +
+ `sweep protocol, and uncertainty. High series resistance, low shunt resistance, ` +
+ `recombination, or measurement artefacts can all reduce FF; one light sweep ` +
+ `cannot identify the cause by itself.`
);
}
function resistances(dataset, allMetrics) {
const lines = dataset.conditions
- .map((c) => allMetrics[c] && `• ${c}: Rs ≈ ${fmt.rs(allMetrics[c])}, Rsh ≈ ${fmt.rsh(allMetrics[c])}`)
+ .map((c) => {
+ const m = allMetrics[c];
+ return m && m.quality !== "invalid" && `• ${c}: Rs ≈ ${fmt.rs(m)}, Rsh ≈ ${fmt.rsh(m)}`;
+ })
.filter(Boolean);
return (
`Series (Rs) and shunt (Rsh) resistance estimates, from the I-V slope near ` +
@@ -90,7 +102,7 @@ function resistances(dataset, allMetrics) {
function nextSteps() {
return (
"Suggested next experiments:\n" +
- "1. Measure under calibrated AM1.5G (1000 W/m²) to report STC efficiency.\n" +
+ "1. If reporting STC performance, use a calibrated AM1.5G-equivalent setup at 1000 W/m² and control device temperature.\n" +
"2. Run a temperature sweep to extract dV_oc/dT and dI_sc/dT coefficients.\n" +
"3. Acquire a dark I-V curve to separate Rs, Rsh and the diode ideality factor.\n" +
"4. Repeat sweeps to quantify measurement repeatability (error bars).\n" +
@@ -128,10 +140,12 @@ export function analyze(message, ctx) {
if (/voc|open.?circuit/.test(l)) {
const r = rankBy(dataset, allMetrics, "voc")[0];
+ if (!r) return "No reportable Voc is available. The sweep must include a positive-to-negative current crossing at non-negative voltage.";
return `Voc is the voltage at zero current (the I-V curve's x-intercept). Highest here: ${r.c} at ${fmt.voc(r.m)}.`;
}
if (/isc|short.?circuit/.test(l)) {
const r = rankBy(dataset, allMetrics, "isc")[0];
+ if (!r) return "No reportable Isc is available. Check the current sign convention and whether the sweep reaches or brackets V = 0.";
return `Isc is the current at zero volts. Highest here: ${r.c} at ${fmt.isc(r.m)}.`;
}
diff --git a/src/lib/assistant.test.js b/src/lib/assistant.test.js
new file mode 100644
index 0000000..7987e23
--- /dev/null
+++ b/src/lib/assistant.test.js
@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+import { analyze } from "./assistant.js";
+import { calcMetrics } from "./ivAnalysis.js";
+
+const dataset = {
+ name: "Assistant fixture",
+ conditions: ["Validated", "Censored", "Invalid"],
+ ivData: {
+ Validated: [
+ { voltage: 0, rawCurrent: 1 },
+ { voltage: 0.5, rawCurrent: 0.5 },
+ { voltage: 1, rawCurrent: 0 },
+ { voltage: 1.1, rawCurrent: -0.1 },
+ ],
+ Censored: [
+ { voltage: 0, rawCurrent: 1 },
+ { voltage: 0.5, rawCurrent: 0.8 },
+ { voltage: 1, rawCurrent: 0.6 },
+ ],
+ Invalid: [
+ { voltage: 0, rawCurrent: -1 },
+ { voltage: 0.5, rawCurrent: -0.5 },
+ { voltage: 1, rawCurrent: 0 },
+ ],
+ },
+};
+
+const allMetrics = Object.fromEntries(
+ dataset.conditions.map((condition) => [condition, calcMetrics(dataset.ivData[condition])])
+);
+
+describe("deterministic assistant validity handling", () => {
+ it("summarizes bounds and withheld values without presenting them as exact", () => {
+ const answer = analyze("summarize", { dataset, allMetrics, efficiency: null });
+ expect(answer).toMatch(/Censored \[REVIEW\].*Voc ≥ 1\.000 V, FF withheld/s);
+ expect(answer).toMatch(/Invalid \[INVALID\]: metrics are not reportable/);
+ expect(answer).toMatch(/Highest reportable Pmax: Validated/);
+ expect(answer).not.toMatch(/Highest reportable Pmax: Censored/);
+ });
+
+ it("ranks only reportable Pmax values", () => {
+ const answer = analyze("compare", { dataset, allMetrics, efficiency: null });
+ expect(answer).toContain("Validated");
+ expect(answer).not.toContain("Censored");
+ expect(answer).not.toContain("Invalid");
+ });
+
+ it("withholds invalid or censored fill factor values", () => {
+ const answer = analyze("fill factor", { dataset, allMetrics, efficiency: null });
+ expect(answer).toContain("Best: Validated");
+ expect(answer).toContain("one light sweep cannot identify the cause");
+ });
+
+ it("does not report an unbracketed Voc as the highest reportable value", () => {
+ const answer = analyze("Voc", { dataset, allMetrics, efficiency: null });
+ expect(answer).toContain("Highest here: Validated");
+ expect(answer).not.toContain("Censored");
+ });
+});
diff --git a/src/lib/ivAnalysis.js b/src/lib/ivAnalysis.js
index 7409b38..e128e52 100644
--- a/src/lib/ivAnalysis.js
+++ b/src/lib/ivAnalysis.js
@@ -22,14 +22,19 @@
* - current : |rawCurrent|, kept only for legacy display helpers
*/
+export const ANALYSIS_VERSION = "4.0.0";
+export const ANALYSIS_METHOD = "piecewise-linear-v4";
+const MAX_WORKSHEET_ROWS = 250000;
+const MAX_WORKSHEET_COLUMNS = 2048;
+
/** Linear interpolation of y at target x between (x0,y0) and (x1,y1). */
function lerp(x, x0, y0, x1, y1) {
if (x1 === x0) return y0;
return y0 + ((x - x0) * (y1 - y0)) / (x1 - x0);
}
-/** Least-squares slope of y(x); null when degenerate (fewer than 2 points or all x equal). */
-function lsqSlope(xs, ys) {
+/** Least-squares line fit of y(x); null when degenerate. */
+function linearFit(xs, ys) {
const n = xs.length;
if (n < 2) return null;
let sx = 0, sy = 0, sxx = 0, sxy = 0;
@@ -37,8 +42,27 @@ function lsqSlope(xs, ys) {
sx += xs[k]; sy += ys[k]; sxx += xs[k] * xs[k]; sxy += xs[k] * ys[k];
}
const den = n * sxx - sx * sx;
- if (den === 0) return null;
- return (n * sxy - sx * sy) / den;
+ if (!Number.isFinite(den) || den === 0) return null;
+ const slope = (n * sxy - sx * sy) / den;
+ const intercept = (sy - slope * sx) / n;
+ if (!Number.isFinite(slope) || !Number.isFinite(intercept)) return null;
+ const mean = sy / n;
+ let ssRes = 0, ssTot = 0;
+ for (let k = 0; k < n; k++) {
+ ssRes += (ys[k] - (intercept + slope * xs[k])) ** 2;
+ ssTot += (ys[k] - mean) ** 2;
+ }
+ const r2 = ssTot === 0 ? 1 : 1 - ssRes / ssTot;
+ return { slope, intercept, r2, points: n, rmse: Math.sqrt(ssRes / n) };
+}
+
+function finiteNumber(value) {
+ if (typeof value === "number") return Number.isFinite(value) ? value : NaN;
+ if (typeof value === "string" && value.trim() !== "") {
+ const parsed = Number(value);
+ return Number.isFinite(parsed) ? parsed : NaN;
+ }
+ return NaN;
}
/**
@@ -47,8 +71,75 @@ function lsqSlope(xs, ys) {
*/
function signedCurrent(pt) {
if (pt == null) return NaN;
- if (typeof pt.rawCurrent === "number") return pt.rawCurrent;
- return Number(pt.current);
+ if (pt.rawCurrent != null) return finiteNumber(pt.rawCurrent);
+ return finiteNumber(pt.current);
+}
+
+/**
+ * Clean a sweep and average repeated samples at the exact same voltage.
+ * Repeated setpoints are common in exported instrument data; averaging makes
+ * extraction deterministic while the returned duplicate count ensures the
+ * operation is never silent.
+ */
+function normalizeSweep(pts) {
+ const raw = pts
+ .map((p) => ({ v: finiteNumber(p && p.voltage), i: signedCurrent(p) }))
+ .filter((p) => Number.isFinite(p.v) && Number.isFinite(p.i))
+ .sort((a, b) => a.v - b.v);
+ const clean = [];
+ for (const point of raw) {
+ const last = clean[clean.length - 1];
+ if (last && last.v === point.v) {
+ last.sum += point.i;
+ last.count++;
+ last.i = last.sum / last.count;
+ } else {
+ clean.push({ v: point.v, i: point.i, sum: point.i, count: 1 });
+ }
+ }
+ return {
+ clean: clean.map(({ v, i }) => ({ v, i })),
+ rawCount: raw.length,
+ duplicateCount: raw.length - clean.length,
+ };
+}
+
+function medianPositiveStep(values) {
+ const steps = [];
+ for (let k = 1; k < values.length; k++) {
+ const step = values[k] - values[k - 1];
+ if (step > 0) steps.push(step);
+ }
+ if (!steps.length) return 0;
+ steps.sort((a, b) => a - b);
+ const mid = Math.floor(steps.length / 2);
+ return steps.length % 2 ? steps[mid] : (steps[mid - 1] + steps[mid]) / 2;
+}
+
+/**
+ * Fit I(V) locally around a target voltage. At most seven nearest samples are
+ * used so distant reverse-bias or knee data cannot dominate an endpoint slope.
+ */
+function localCurrentFit(v, i, target, characteristicSpan) {
+ const step = medianPositiveStep(v);
+ const radius = Math.max(characteristicSpan, 3 * step);
+ let indices = v
+ .map((value, index) => ({ index, distance: Math.abs(value - target) }))
+ .filter((entry) => entry.distance <= radius + Number.EPSILON)
+ .sort((a, b) => a.distance - b.distance);
+ if (indices.length < 3) {
+ indices = v
+ .map((value, index) => ({ index, distance: Math.abs(value - target) }))
+ .sort((a, b) => a.distance - b.distance)
+ .slice(0, 3);
+ } else {
+ indices = indices.slice(0, 7);
+ }
+ indices.sort((a, b) => v[a.index] - v[b.index]);
+ const xs = indices.map((entry) => v[entry.index]);
+ const ys = indices.map((entry) => i[entry.index]);
+ const result = linearFit(xs, ys);
+ return result ? { ...result, voltageSpan: xs[xs.length - 1] - xs[0] } : null;
}
/**
@@ -57,38 +148,51 @@ function signedCurrent(pt) {
* @param {Array<{voltage:number, current?:number, rawCurrent?:number}>} pts
* Measured points. Order does not matter — points are sorted by voltage.
* @returns {null | {
- * isc:number, voc:number, pmax:number, vmp:number, imp:number,
- * ff:number, rs:number, rsh:number, crossIndex:number,
- * notes:{ iscExtrapolated:boolean, vocBeyondRange:boolean },
- * warnings:string[]
- * }} All electrical quantities in SI base units (V, A, W, Ω). `ff` is a
- * fraction in [0,1]. `warnings` lists human-readable data-quality flags
- * (empty for a clean sweep). Returns null when fewer than 3 valid points
- * are given.
+ * isc:number, voc:number|null, pmax:number, vmp:number, imp:number,
+ * ff:number|null, rs:number|null, rsh:number|null, crossIndex:number,
+ * notes:{ iscExtrapolated:boolean, vocBeyondRange:boolean, vocAmbiguous:boolean, duplicateVoltages:number },
+ * status:Record, warnings:string[], errors:string[],
+ * quality:"pass"|"review"|"invalid"
+ * }} Electrical quantities use SI base units (V, A, W, Ω). `ff` is a
+ * dimensionless fraction when identifiable. Status fields distinguish
+ * measured, interpolated, extrapolated, provisional, and withheld results.
+ * Returns null when fewer than 3 finite, unique-voltage samples remain.
*/
export function calcMetrics(pts) {
if (!Array.isArray(pts) || pts.length < 3) return null;
- // Build clean, voltage-sorted arrays of finite samples.
- const clean = pts
- .map((p) => ({ v: Number(p.voltage), i: signedCurrent(p) }))
- .filter((p) => Number.isFinite(p.v) && Number.isFinite(p.i))
- .sort((a, b) => a.v - b.v);
+ // Build clean, voltage-sorted arrays of finite, unique-voltage samples.
+ const normalized = normalizeSweep(pts);
+ const clean = normalized.clean;
const n = clean.length;
if (n < 3) return null;
const v = clean.map((p) => p.v);
const i = clean.map((p) => p.i);
- const notes = { iscExtrapolated: false, vocBeyondRange: false };
+ const notes = {
+ iscExtrapolated: false,
+ vocBeyondRange: false,
+ vocAmbiguous: false,
+ duplicateVoltages: normalized.duplicateCount,
+ };
+ const status = {
+ isc: "unavailable",
+ voc: "unavailable",
+ pmax: "unavailable",
+ ff: "unavailable",
+ rs: "unavailable",
+ rsh: "unavailable",
+ };
// ── Short-circuit current Isc = I(V = 0) ─────────────────────────────────
// Prefer an exact V=0 sample, else interpolate across the bracketing pair,
- // else linearly extrapolate from the two lowest-voltage points to V=0.
+ // else linearly extrapolate from the two samples nearest V=0.
let isc;
const zeroExact = v.indexOf(0);
if (zeroExact !== -1) {
isc = i[zeroExact];
+ status.isc = "measured";
} else {
let bracket = -1;
for (let j = 0; j < n - 1; j++) {
@@ -99,28 +203,51 @@ export function calcMetrics(pts) {
}
if (bracket !== -1) {
isc = lerp(0, v[bracket], i[bracket], v[bracket + 1], i[bracket + 1]);
+ status.isc = "interpolated";
} else {
- // All samples on one side of V=0: extrapolate from the nearest two.
- isc = lerp(0, v[0], i[0], v[1], i[1]);
+ const nearest = clean
+ .map((point) => ({ ...point, distance: Math.abs(point.v) }))
+ .sort((a, b) => a.distance - b.distance)
+ .slice(0, 2)
+ .sort((a, b) => a.v - b.v);
+ isc = lerp(0, nearest[0].v, nearest[0].i, nearest[1].v, nearest[1].i);
notes.iscExtrapolated = true;
+ status.isc = "extrapolated";
}
}
// ── Open-circuit voltage Voc = V where I first crosses 0 going negative ───
let voc = null;
let crossIndex = -1;
+ const vocCandidates = [];
for (let j = 1; j < n; j++) {
if (i[j - 1] > 0 && i[j] <= 0) {
- voc = lerp(0, i[j - 1], v[j - 1], i[j], v[j]); // interpolate V at I=0
- crossIndex = j;
- break;
+ const candidate = lerp(0, i[j - 1], v[j - 1], i[j], v[j]);
+ if (candidate >= 0) {
+ vocCandidates.push({
+ voltage: candidate,
+ index: j,
+ status: i[j] === 0 ? "measured" : "interpolated",
+ });
+ }
}
}
- if (voc === null) {
- // Current never reaches zero within the sweep — report the last voltage
- // and flag that Voc lies beyond the measured range.
- voc = v[n - 1];
- notes.vocBeyondRange = true;
+ if (vocCandidates.length === 1) {
+ voc = vocCandidates[0].voltage;
+ crossIndex = vocCandidates[0].index;
+ status.voc = vocCandidates[0].status;
+ } else if (vocCandidates.length > 1) {
+ notes.vocAmbiguous = true;
+ status.voc = "ambiguous";
+ } else {
+ const nonnegative = clean.filter((point) => point.v >= 0);
+ if (nonnegative.some((point) => point.i > 0)) {
+ // Keep the boundary value for charting/backward compatibility, but mark
+ // it explicitly as a lower bound and do not derive FF or Rs from it.
+ voc = nonnegative[nonnegative.length - 1].v;
+ notes.vocBeyondRange = true;
+ status.voc = "lower-bound";
+ }
}
// ── Maximum power point — restricted to the power quadrant (V≥0, I≥0) ─────
@@ -134,61 +261,96 @@ export function calcMetrics(pts) {
let pmax = 0;
let vmp = 0;
let imp = 0;
- const considerMpp = (vv, ii) => {
- if (vv < 0 || ii < 0) return;
+ let mppSource = "unavailable";
+ let mppOverflow = false;
+ const considerMpp = (vv, ii, source) => {
+ if (vv < 0 || ii < 0 || (voc != null && status.voc !== "lower-bound" && vv > voc + 1e-12)) return;
const p = vv * ii;
- if (p > pmax) { pmax = p; vmp = vv; imp = ii; }
+ if (!Number.isFinite(p)) { mppOverflow = true; return; }
+ if (p > pmax) { pmax = p; vmp = vv; imp = ii; mppSource = source; }
};
- for (let j = 0; j < n; j++) considerMpp(v[j], i[j]);
+ for (let j = 0; j < n; j++) considerMpp(v[j], i[j], "measured");
for (let j = 0; j < n - 1; j++) {
const dv = v[j + 1] - v[j];
- if (dv <= 0) continue; // duplicate abscissa — no interior to search
+ if (dv <= 0) continue;
const b = (i[j + 1] - i[j]) / dv;
if (b >= 0) continue; // parabola opens upward or is flat: endpoints suffice
const a = i[j] - b * v[j];
const vStar = -a / (2 * b);
- if (vStar > v[j] && vStar < v[j + 1]) considerMpp(vStar, a + b * vStar);
+ if (vStar > v[j] && vStar < v[j + 1]) considerMpp(vStar, a + b * vStar, "interpolated");
}
+ if (pmax > 0) status.pmax = status.voc === "lower-bound" ? "provisional" : mppSource;
// ── Fill factor FF = Pmax / (Isc · Voc) ──────────────────────────────────
// Uses the Pmax actually found on the P-V curve above — never the
// Voc·Isc·(assumed FF) shortcut.
- const ff = isc > 0 && voc > 0 ? pmax / (isc * voc) : 0;
-
- // ── Series resistance Rs ≈ −dV/dI at the I = 0 crossing (near Voc) ────────
- // Slope of the single segment that brackets the crossing — the most local
- // estimate available from one light sweep.
- let rs = 0;
- if (crossIndex >= 1) {
- const dv = v[crossIndex] - v[crossIndex - 1];
- const di = i[crossIndex] - i[crossIndex - 1];
- if (di !== 0) rs = Math.abs(dv / di);
+ let ff = null;
+ if (isc > 0 && voc > 0 && (status.voc === "measured" || status.voc === "interpolated")) {
+ ff = pmax / (isc * voc);
+ status.ff = status.isc === "extrapolated" ? "provisional" : "computed";
}
- // ── Shunt resistance Rsh ≈ (dI/dV)⁻¹ near short circuit ──────────────────
- // Least-squares slope of I(V) over the low-voltage plateau (V ≤ 30 % of Voc,
- // including any reverse-bias samples) — more noise-robust than a two-point
- // difference. Falls back to the three lowest-voltage samples when the
- // plateau holds fewer than three points.
- let rsh = Infinity;
- {
- const cut = voc > 0 ? 0.3 * voc : v[0] + 0.3 * (v[n - 1] - v[0]);
- let xs = [], ys = [];
- for (let j = 0; j < n; j++) if (v[j] <= cut) { xs.push(v[j]); ys.push(i[j]); }
- if (xs.length < 3) { xs = v.slice(0, 3); ys = i.slice(0, 3); }
- const slope = lsqSlope(xs, ys);
- if (slope !== null && slope !== 0) rsh = Math.abs(1 / slope);
+ // ── Endpoint resistance estimates ─────────────────────────────────────────
+ // Fit the nearest local samples rather than using one noise-sensitive pair.
+ // These remain slope estimates from a light sweep, not single-diode fits.
+ let rs = null;
+ let rsFit = null;
+ if (voc != null && (status.voc === "measured" || status.voc === "interpolated")) {
+ rsFit = localCurrentFit(v, i, voc, 0.08 * Math.max(voc, medianPositiveStep(v)));
+ if (rsFit && rsFit.slope !== 0) {
+ const estimate = Math.abs(1 / rsFit.slope);
+ if (Number.isFinite(estimate)) {
+ rs = estimate;
+ status.rs = "estimated";
+ }
+ }
+ }
+
+ let rsh = null;
+ const rshFit = localCurrentFit(
+ v,
+ i,
+ 0,
+ 0.08 * Math.max(voc || (v[n - 1] - v[0]), medianPositiveStep(v))
+ );
+ if (rshFit) {
+ rsh = rshFit.slope === 0 ? Infinity : Math.abs(1 / rshFit.slope);
+ status.rsh = status.isc === "extrapolated" ? "provisional" : "estimated";
}
// ── Data-quality warnings ─────────────────────────────────────────────────
// Sanity checks a reviewer would run by eye; surfaced verbatim in the UI.
const warnings = [];
+ const errors = [];
+ if (normalized.duplicateCount > 0)
+ warnings.push(`${normalized.duplicateCount} repeated voltage sample(s) were averaged before extraction — split forward/reverse sweeps into separate channels if these repeats represent hysteresis.`);
if (notes.iscExtrapolated)
- warnings.push("No samples bracket V = 0 — Isc is a linear extrapolation from the two lowest-voltage points.");
+ warnings.push("No samples bracket V = 0 — Isc is a linear extrapolation from the two nearest voltage points.");
if (notes.vocBeyondRange)
- warnings.push("Current never crosses zero within the sweep — the quoted Voc is the last measured voltage (a lower bound).");
+ warnings.push("Current never crosses zero within the sweep — Voc is reported only as a lower bound; FF and Rs are withheld and Pmax is provisional.");
+ if (notes.vocAmbiguous)
+ errors.push(`Current crosses from positive to non-positive ${vocCandidates.length} times at non-negative voltage — Voc is ambiguous, so Voc, FF, and Rs are withheld.`);
+ if (!Number.isFinite(isc))
+ errors.push("Isc calculation overflowed or became non-finite — inspect extreme values, units, and corrupt cells.");
+ if (mppOverflow) {
+ status.pmax = "overflow";
+ errors.push("At least one V·I product overflowed the numeric range — power metrics are not reportable; inspect extreme values and units.");
+ }
+ if (ff != null && !Number.isFinite(ff)) {
+ status.ff = "unavailable";
+ errors.push("Fill-factor calculation became non-finite — power metrics are not reportable; inspect extreme values and units.");
+ ff = null;
+ }
if (isc <= 0)
- warnings.push("Isc ≤ 0. For an illuminated cell in generator convention Isc should be positive — check the current sign or column mapping.");
+ errors.push("Isc ≤ 0. Solavin requires generator convention (positive current in the power quadrant); invert the current sign or correct the column mapping.");
+ if (!v.some((value) => value >= 0))
+ errors.push("The sweep contains no non-negative voltage samples, so photovoltaic power-quadrant metrics are not identifiable.");
+ if (voc === null && !notes.vocAmbiguous)
+ errors.push("No non-negative open-circuit crossing or lower bound can be identified from this sweep.");
+ if (ff != null && (ff < 0 || ff > 1 + 1e-9)) {
+ status.ff = "unphysical";
+ errors.push(`Computed fill factor is ${(ff * 100).toFixed(2)} %, outside the physical 0–100 % interval — inspect sign convention, sweep coverage, and outliers.`);
+ }
// Monotonicity: between V = 0 and Voc an illuminated cell's current should
// fall as voltage rises. Tolerate noise up to 2 % of the Isc scale.
{
@@ -196,7 +358,8 @@ export function calcMetrics(pts) {
const tol = 0.02 * scale;
let rises = 0;
for (let j = 1; j < n; j++) {
- if (v[j - 1] < 0 || v[j] > voc + 1e-12) continue;
+ const limit = voc == null ? v[n - 1] : voc;
+ if (v[j - 1] < 0 || v[j] > limit + 1e-12) continue;
if (i[j] - i[j - 1] > tol) rises++;
}
if (rises > 0)
@@ -210,7 +373,18 @@ export function calcMetrics(pts) {
warnings.push(`Only ${quad} sweep point(s) fall in the power quadrant (V ≥ 0, I ≥ 0) — Vmp/Imp resolution is limited; use a finer voltage step.`);
}
- return { isc, voc, pmax, vmp, imp, ff, rs, rsh, crossIndex, notes, warnings };
+ const quality = errors.length ? "invalid" : warnings.length ? "review" : "pass";
+ return {
+ isc, voc, pmax, vmp, imp, ff, rs, rsh, crossIndex,
+ sampleCount: normalized.rawCount,
+ uniqueVoltageCount: n,
+ notes,
+ status,
+ fit: { rs: rsFit, rsh: rshFit },
+ warnings,
+ errors,
+ quality,
+ };
}
/**
@@ -247,11 +421,15 @@ export function fmtSI(value, unit, digits = 3) {
* @returns {number|null} Efficiency in percent, or null for invalid inputs.
*/
export function computeEfficiency(pmaxW, areaCm2, irradiance) {
+ const p = Number(pmaxW);
const a = Number(areaCm2);
const g = Number(irradiance);
- if (!Number.isFinite(a) || !Number.isFinite(g) || a <= 0 || g <= 0) return null;
+ if (!Number.isFinite(p) || !Number.isFinite(a) || !Number.isFinite(g) || p < 0 || a <= 0 || g <= 0) return null;
const areaM2 = a * 1e-4; // cm² → m²
- return (pmaxW / (g * areaM2)) * 100;
+ const incidentPower = g * areaM2;
+ if (!Number.isFinite(incidentPower) || incidentPower <= 0) return null;
+ const efficiency = (p / incidentPower) * 100;
+ return Number.isFinite(efficiency) ? efficiency : null;
}
/**
@@ -259,28 +437,185 @@ export function computeEfficiency(pmaxW, areaCm2, irradiance) {
* sweeps, row 0 = headers) into a structured dataset fragment.
*
* @param {Array>} rows
- * @returns {null | { conditions:string[], ivData:Record }}
+ * Missing/blank cells are skipped, never coerced to zero. Header names are
+ * made unique so one channel cannot silently overwrite another.
+ *
+ * @returns {null | {
+ * conditions:string[],
+ * ivData:Record,
+ * diagnostics:{warnings:string[], rows:number, channels:Record}
+ * }}
*/
export function extractIV(rows) {
- if (!rows || rows.length < 3) return null;
- const header = rows[0]
- .slice(1)
- .map((x, idx) => (x == null || x === "" ? `Channel ${idx + 1}` : String(x)));
- const conditions = header.filter((_, idx) => rows[0][idx + 1] != null && rows[0][idx + 1] !== "");
+ if (!Array.isArray(rows) || rows.length < 2 || !Array.isArray(rows[0])) return null;
+ if (rows.length - 1 > MAX_WORKSHEET_ROWS)
+ throw new Error(`Worksheet exceeds the ${MAX_WORKSHEET_ROWS.toLocaleString()}-data-row safety limit.`);
+ const dataRows = rows.slice(1).filter(Array.isArray);
+ const maxColumns = rows.reduce((max, row) => (Array.isArray(row) ? Math.max(max, row.length) : max), 0);
+ if (maxColumns < 2) return null;
+ if (maxColumns > MAX_WORKSHEET_COLUMNS)
+ throw new Error(`Worksheet exceeds the ${MAX_WORKSHEET_COLUMNS.toLocaleString()}-column safety limit.`);
+
+ const warnings = [];
+ const channels = Object.create(null);
+ const ivData = Object.create(null);
+ const conditions = [];
+ const nameCounts = new Map();
+ let invalidVoltageRows = 0;
+ for (const row of dataRows) {
+ if (!Number.isFinite(finiteNumber(row[0]))) invalidVoltageRows++;
+ }
+
+ const uniqueName = (raw, columnIndex) => {
+ let base = raw == null || String(raw).trim() === ""
+ ? `Channel ${columnIndex}`
+ : String(raw).trim().slice(0, 120);
+ if (["__proto__", "prototype", "constructor"].includes(base)) base = `Channel: ${base}`;
+ const count = (nameCounts.get(base) || 0) + 1;
+ nameCounts.set(base, count);
+ return count === 1 ? base : `${base} (${count})`;
+ };
+
+ for (let columnIndex = 1; columnIndex < maxColumns; columnIndex++) {
+ const hasHeader = rows[0][columnIndex] != null && String(rows[0][columnIndex]).trim() !== "";
+ const hasAnyCell = dataRows.some((row) => row[columnIndex] != null && String(row[columnIndex]).trim() !== "");
+ if (!hasHeader && !hasAnyCell) continue;
+
+ const name = uniqueName(rows[0][columnIndex], columnIndex);
+ const points = [];
+ let skippedCurrent = 0;
+ for (const row of dataRows) {
+ const voltage = finiteNumber(row[0]);
+ const current = finiteNumber(row[columnIndex]);
+ if (!Number.isFinite(voltage)) continue;
+ if (!Number.isFinite(current)) {
+ skippedCurrent++;
+ continue;
+ }
+ points.push({ voltage, current: Math.abs(current), rawCurrent: current });
+ }
+
+ const uniqueVoltages = new Set(points.map((point) => point.voltage)).size;
+ if (points.length < 3 || uniqueVoltages < 3) {
+ warnings.push(`Column ${columnIndex + 1} (${name}) was ignored because it contains ${points.length} valid pair(s) across ${uniqueVoltages} unique voltage(s); at least 3 unique voltages are required.`);
+ continue;
+ }
+ if (!hasHeader) warnings.push(`Column ${columnIndex + 1} had no header and was named "${name}".`);
+ if (nameCounts.get(String(rows[0][columnIndex] ?? "").trim()) > 1)
+ warnings.push(`Duplicate channel header "${String(rows[0][columnIndex]).trim()}" was renamed "${name}".`);
+ if (skippedCurrent > 0)
+ warnings.push(`${name}: skipped ${skippedCurrent} row(s) with a blank or non-numeric current; no zero values were inserted.`);
+
+ conditions.push(name);
+ ivData[name] = points;
+ channels[name] = {
+ column: columnIndex + 1,
+ validPoints: points.length,
+ uniqueVoltages,
+ skippedCurrent,
+ };
+ }
if (conditions.length === 0) return null;
+ if (invalidVoltageRows > 0)
+ warnings.push(`Skipped ${invalidVoltageRows} row(s) with a blank or non-numeric voltage.`);
- const dataRows = rows.slice(1).filter((r) => r[0] != null && r[0] !== "");
- const ivData = {};
- conditions.forEach((name, ci) => {
- ivData[name] = dataRows
- .map((r) => {
- const voltage = Number(r[0]);
- const raw = Number(r[ci + 1] ?? 0);
- return { voltage, current: Math.abs(raw), rawCurrent: raw };
- })
- .filter((p) => Number.isFinite(p.voltage) && Number.isFinite(p.rawCurrent));
- });
- return { conditions, ivData };
+ return {
+ conditions,
+ ivData,
+ diagnostics: {
+ warnings,
+ rows: dataRows.length,
+ invalidVoltageRows,
+ channels,
+ },
+ };
+}
+
+/**
+ * Parse RFC 4180-style CSV text without executing formulas or coercing values.
+ * Numeric conversion happens later in extractIV().
+ */
+export function parseCsv(text, limits = {}) {
+ if (typeof text !== "string") throw new TypeError("CSV input must be text.");
+ const maxRows = limits.maxRows || 250000;
+ const maxColumns = limits.maxColumns || 2048;
+ const source = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+ const rows = [];
+ let row = [];
+ let field = "";
+ let quoted = false;
+
+ const pushField = () => {
+ row.push(field);
+ field = "";
+ if (row.length > maxColumns) throw new Error(`CSV exceeds the ${maxColumns}-column safety limit.`);
+ };
+ const pushRow = () => {
+ pushField();
+ rows.push(row);
+ row = [];
+ if (rows.length > maxRows) throw new Error(`CSV exceeds the ${maxRows.toLocaleString()}-row safety limit.`);
+ };
+
+ for (let index = 0; index < source.length; index++) {
+ const char = source[index];
+ if (quoted) {
+ if (char === '"') {
+ if (source[index + 1] === '"') {
+ field += '"';
+ index++;
+ } else {
+ quoted = false;
+ }
+ } else {
+ field += char;
+ }
+ continue;
+ }
+ if (char === '"' && field === "") {
+ quoted = true;
+ } else if (char === ",") {
+ pushField();
+ } else if (char === "\n" || char === "\r") {
+ if (char === "\r" && source[index + 1] === "\n") index++;
+ pushRow();
+ } else {
+ field += char;
+ }
+ }
+ if (quoted) throw new Error("CSV contains an unterminated quoted field.");
+ if (field !== "" || row.length > 0) pushRow();
+ while (rows.length && rows[rows.length - 1].every((cell) => cell === "")) rows.pop();
+ return rows;
+}
+
+/**
+ * Align channels by numeric voltage rather than array index. Sparse channels
+ * retain null gaps, preventing a missing cell from shifting every later point
+ * onto the wrong x-coordinate.
+ */
+export function buildAlignedRows(dataset, selectedConditions, valueForPoint = (point) => point.rawCurrent) {
+ if (!dataset || !Array.isArray(dataset.conditions) || !dataset.ivData) return [];
+ const conditions = Array.isArray(selectedConditions) ? selectedConditions : dataset.conditions;
+ const rowsByVoltage = new Map();
+ for (const condition of conditions) {
+ const samplesByVoltage = new Map();
+ for (const point of dataset.ivData[condition] || []) {
+ const voltage = finiteNumber(point && point.voltage);
+ const value = valueForPoint(point, condition);
+ if (!Number.isFinite(voltage) || !Number.isFinite(value)) continue;
+ const group = samplesByVoltage.get(voltage) || { sum: 0, count: 0 };
+ group.sum += value;
+ group.count++;
+ samplesByVoltage.set(voltage, group);
+ }
+ for (const [voltage, group] of samplesByVoltage) {
+ const row = rowsByVoltage.get(voltage) || { voltage };
+ row[condition] = group.sum / group.count;
+ rowsByVoltage.set(voltage, row);
+ }
+ }
+ return [...rowsByVoltage.values()].sort((a, b) => a.voltage - b.voltage);
}
/**
@@ -327,7 +662,12 @@ export function buildSampleDataset() {
rawCurrent: r[ci + 1],
}));
});
- return { name: "Sample: Solar Cell (Room Lights)", conditions, ivData };
+ return {
+ name: "Sample: Solar Cell (Room Lights)",
+ conditions,
+ ivData,
+ source: { file: "examples/sample_iv_data.csv", sheet: "CSV" },
+ };
}
/**
@@ -340,12 +680,13 @@ export function buildSampleDataset() {
* @param {{conditions:string[]}} dataset
* @param {Record>} allMetrics
* @param {Record|null} [efficiency] optional η (%) per condition
+ * @param {{cellAreaCm2?:number, irradianceWm2?:number}} [efficiencyInputs]
*/
-export function metricsToRows(dataset, allMetrics, efficiency) {
+export function metricsToRows(dataset, allMetrics, efficiency, efficiencyInputs = {}) {
const ms = dataset.conditions.map((c) => allMetrics[c]).filter(Boolean);
const iScale = siPrefix(Math.max(0, ...ms.map((m) => Math.abs(m.isc)), ...ms.map((m) => Math.abs(m.imp))));
const pScale = siPrefix(Math.max(0, ...ms.map((m) => Math.abs(m.pmax))));
- const rsScale = siPrefix(Math.max(0, ...ms.map((m) => Math.abs(m.rs))));
+ const rsScale = siPrefix(Math.max(0, ...ms.filter((m) => Number.isFinite(m.rs)).map((m) => Math.abs(m.rs))));
const rshScale = siPrefix(Math.max(0, ...ms.filter((m) => Number.isFinite(m.rsh)).map((m) => Math.abs(m.rsh))));
const ascii = (p) => (p === "µ" ? "u" : p);
const header = [
@@ -359,35 +700,122 @@ export function metricsToRows(dataset, allMetrics, efficiency) {
`Rs (${ascii(rsScale.prefix)}Ohm)`,
`Rsh (${ascii(rshScale.prefix)}Ohm)`,
];
- if (efficiency) header.push("Efficiency (%)");
+ if (efficiency) header.push(
+ "Efficiency (%)",
+ "Efficiency status",
+ "Cell area (cm2)",
+ "Irradiance (W/m2)"
+ );
+ header.push(
+ "Isc status",
+ "Voc status",
+ "Pmax status",
+ "FF status",
+ "Quality",
+ "Valid samples",
+ "Unique voltages",
+ "Metric flags",
+ "Import flags",
+ "Source file",
+ "Source sheet",
+ "Analysis version",
+ "Analysis method"
+ );
+ const importFlags = (dataset.diagnostics?.warnings || []).join(" | ");
const rows = [header];
dataset.conditions.forEach((c) => {
const m = allMetrics[c];
if (!m) return;
+ const efficiencyValue = efficiency?.[c];
+ const hasEfficiency = Number.isFinite(efficiencyValue);
+ const metricFlags = [...(m.errors || []), ...(m.warnings || [])];
+ const hasPmax = ["measured", "interpolated", "provisional"].includes(m.status?.pmax);
+ if (Number.isFinite(efficiencyValue) && efficiencyValue > 100)
+ metricFlags.push(`Computed efficiency is ${efficiencyValue.toPrecision(4)} %, above the physical 100 % limit — verify area, irradiance, units, and measurement conditions.`);
const row = [
c,
- +(m.isc / iScale.div).toFixed(4),
- +m.voc.toFixed(4),
- +(m.pmax / pScale.div).toFixed(4),
- +m.vmp.toFixed(4),
- +(m.imp / iScale.div).toFixed(4),
- +(m.ff * 100).toFixed(2),
- +(m.rs / rsScale.div).toFixed(3),
- m.rsh === Infinity ? "Inf" : +(m.rsh / rshScale.div).toFixed(3),
+ Number.isFinite(m.isc) ? +(m.isc / iScale.div).toFixed(4) : "",
+ Number.isFinite(m.voc) ? +m.voc.toFixed(4) : "",
+ hasPmax ? +(m.pmax / pScale.div).toFixed(4) : "",
+ hasPmax ? +m.vmp.toFixed(4) : "",
+ hasPmax ? +(m.imp / iScale.div).toFixed(4) : "",
+ m.ff == null ? "" : +(m.ff * 100).toFixed(2),
+ m.rs == null ? "" : +(m.rs / rsScale.div).toFixed(3),
+ m.rsh == null ? "" : m.rsh === Infinity ? "Inf" : +(m.rsh / rshScale.div).toFixed(3),
];
- if (efficiency) row.push(efficiency[c] != null ? +efficiency[c].toPrecision(4) : "");
+ if (efficiency) row.push(
+ hasEfficiency ? +efficiencyValue.toPrecision(4) : "",
+ !hasEfficiency ? "" : efficiencyValue > 100 ? "unphysical" : "computed",
+ Number.isFinite(efficiencyInputs.cellAreaCm2) ? efficiencyInputs.cellAreaCm2 : "",
+ Number.isFinite(efficiencyInputs.irradianceWm2) ? efficiencyInputs.irradianceWm2 : ""
+ );
+ row.push(
+ m.status?.isc || "",
+ m.status?.voc || "",
+ m.status?.pmax || "",
+ m.status?.ff || "",
+ m.quality || "",
+ m.sampleCount ?? "",
+ m.uniqueVoltageCount ?? "",
+ metricFlags.join(" | "),
+ importFlags,
+ dataset.source?.file || "",
+ dataset.source?.sheet || "",
+ ANALYSIS_VERSION,
+ ANALYSIS_METHOD
+ );
rows.push(row);
});
return rows;
}
+/**
+ * Export the signed measurements exactly as aligned for visualization.
+ * Missing samples remain blank; duplicate exact-voltage samples are averaged
+ * consistently with buildAlignedRows().
+ */
+export function rawDataToRows(dataset) {
+ if (!dataset || !Array.isArray(dataset.conditions)) return [["Voltage (V)"]];
+ const header = ["Voltage (V)", ...dataset.conditions.map((condition) => `${condition} (A)`)];
+ const body = buildAlignedRows(dataset).map((aligned) => [
+ aligned.voltage,
+ ...dataset.conditions.map((condition) =>
+ Number.isFinite(aligned[condition]) ? aligned[condition] : ""
+ ),
+ ]);
+ return [header, ...body];
+}
+
+/** Export analysis provenance and interpretation rules as a two-column sheet. */
+export function metadataToRows(dataset, efficiencyInputs = {}) {
+ return [
+ ["Field", "Value"],
+ ["Solavin analysis version", ANALYSIS_VERSION],
+ ["Analysis method", ANALYSIS_METHOD],
+ ["Dataset", dataset?.name || ""],
+ ["Source file", dataset?.source?.file || ""],
+ ["Source sheet", dataset?.source?.sheet || ""],
+ ["Cell area (cm2)", Number.isFinite(efficiencyInputs.cellAreaCm2) ? efficiencyInputs.cellAreaCm2 : ""],
+ ["Irradiance (W/m2)", Number.isFinite(efficiencyInputs.irradianceWm2) ? efficiencyInputs.irradianceWm2 : ""],
+ ["Current convention", "Generator convention: positive current produces positive V*I power"],
+ ["Visualization", "Measured samples joined with straight segments; no smoothing"],
+ ["Duplicate voltage handling", "Exact duplicate setpoints are averaged and reported"],
+ ["Missing cell handling", "Missing or non-numeric measurements stay missing; zeros are never inserted"],
+ ["Censored sweep handling", "When Voc is not bracketed, Voc is a lower bound, Pmax is provisional, and FF/Rs are withheld"],
+ ["Import flags", (dataset?.diagnostics?.warnings || []).join(" | ")],
+ ];
+}
+
/** Serialise export rows to a CSV string. */
export function rowsToCsv(rows) {
return rows
.map((r) =>
r
.map((cell) => {
- const s = String(cell);
+ // Prevent spreadsheet formula injection through untrusted channel
+ // labels while leaving numeric negative values numeric.
+ const safe = typeof cell === "string" && /^[=+\-@\t\r]/.test(cell) ? `'${cell}` : cell;
+ const s = String(safe);
return /[",\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s;
})
.join(",")
diff --git a/src/lib/ivAnalysis.test.js b/src/lib/ivAnalysis.test.js
index 314fae4..b6ad916 100644
--- a/src/lib/ivAnalysis.test.js
+++ b/src/lib/ivAnalysis.test.js
@@ -193,7 +193,8 @@ describe("calcMetrics — data-quality warnings", () => {
{ voltage: 0.5, rawCurrent: -1.2 },
{ voltage: 1.0, rawCurrent: -1.4 },
]);
- expect(m.warnings.some((w) => /Isc ≤ 0/.test(w))).toBe(true);
+ expect(m.errors.some((w) => /Isc ≤ 0/.test(w))).toBe(true);
+ expect(m.quality).toBe("invalid");
});
it("flags non-monotonic current between 0 V and Voc", () => {
diff --git a/src/lib/ivAnalysis.validation.test.js b/src/lib/ivAnalysis.validation.test.js
new file mode 100644
index 0000000..26a6059
--- /dev/null
+++ b/src/lib/ivAnalysis.validation.test.js
@@ -0,0 +1,434 @@
+import { describe, expect, it } from "vitest";
+import readExcelFile from "read-excel-file/node";
+import writeExcelFile from "write-excel-file/node";
+import {
+ buildAlignedRows,
+ calcMetrics,
+ computeEfficiency,
+ extractIV,
+ metadataToRows,
+ metricsToRows,
+ parseCsv,
+ rawDataToRows,
+ rowsToCsv,
+} from "./ivAnalysis.js";
+
+function mulberry32(seed) {
+ return () => {
+ let value = seed += 0x6d2b79f5;
+ value = Math.imul(value ^ (value >>> 15), value | 1);
+ value ^= value + Math.imul(value ^ (value >>> 7), value | 61);
+ return ((value ^ (value >>> 14)) >>> 0) / 4294967296;
+ };
+}
+
+function shuffle(values, random) {
+ const result = [...values];
+ for (let index = result.length - 1; index > 0; index--) {
+ const target = Math.floor(random() * (index + 1));
+ [result[index], result[target]] = [result[target], result[index]];
+ }
+ return result;
+}
+
+function maximize(functionToEvaluate, lower, upper) {
+ const ratio = (Math.sqrt(5) - 1) / 2;
+ let left = lower;
+ let right = upper;
+ let x1 = right - ratio * (right - left);
+ let x2 = left + ratio * (right - left);
+ let y1 = functionToEvaluate(x1);
+ let y2 = functionToEvaluate(x2);
+ for (let iteration = 0; iteration < 120; iteration++) {
+ if (y1 > y2) {
+ right = x2;
+ x2 = x1;
+ y2 = y1;
+ x1 = right - ratio * (right - left);
+ y1 = functionToEvaluate(x1);
+ } else {
+ left = x1;
+ x1 = x2;
+ y1 = y2;
+ x2 = left + ratio * (right - left);
+ y2 = functionToEvaluate(x2);
+ }
+ }
+ const x = (left + right) / 2;
+ return { x, y: functionToEvaluate(x) };
+}
+
+describe("accuracy validation — independent analytic oracles", () => {
+ it("recovers 300 deterministic random linear I-V curves to floating-point precision", () => {
+ const random = mulberry32(0x50a71);
+ for (let trial = 0; trial < 300; trial++) {
+ const isc = 10 ** (-8 + 8 * random());
+ const voc = 0.15 + 4.85 * random();
+ const voltages = [0];
+ for (let index = 0; index < 6 + Math.floor(random() * 20); index++) {
+ voltages.push(voc * 1.15 * random());
+ }
+ voltages.push(voc * 1.05);
+ const points = voltages.map((voltage) => ({
+ voltage,
+ rawCurrent: isc * (1 - voltage / voc),
+ }));
+ const metrics = calcMetrics(shuffle(points, random));
+ const expectedPower = isc * voc / 4;
+
+ expect(metrics.isc).toBeCloseTo(isc, 12);
+ expect(metrics.voc).toBeCloseTo(voc, 12);
+ expect(metrics.vmp).toBeCloseTo(voc / 2, 12);
+ expect(metrics.imp).toBeCloseTo(isc / 2, 12);
+ expect(metrics.pmax).toBeCloseTo(expectedPower, 12);
+ expect(metrics.ff).toBeCloseTo(0.25, 12);
+ expect(metrics.errors).toEqual([]);
+ }
+ });
+
+ it("matches a continuous single-diode oracle across scale, Voc, and ideality", () => {
+ const thermalVoltage = 0.025852;
+ const cases = [
+ { isc: 140e-3, voc: 0.60, n: 1.0 },
+ { isc: 35e-3, voc: 0.58, n: 2.0 },
+ { isc: 1.5e-6, voc: 2.08, n: 1.4 },
+ { isc: 4.2, voc: 0.72, n: 1.15 },
+ { isc: 8e-9, voc: 0.42, n: 1.8 },
+ { isc: 0.8, voc: 1.25, n: 1.3 },
+ ];
+
+ for (const testCase of cases) {
+ const saturationCurrent = testCase.isc / Math.expm1(testCase.voc / (testCase.n * thermalVoltage));
+ const currentAt = (voltage) =>
+ testCase.isc - saturationCurrent * Math.expm1(voltage / (testCase.n * thermalVoltage));
+ const oracle = maximize((voltage) => voltage * currentAt(voltage), 0, testCase.voc);
+ const step = testCase.voc / 500;
+ const points = [];
+ for (let voltage = 0; voltage <= testCase.voc * 1.04; voltage += step) {
+ points.push({ voltage, rawCurrent: currentAt(voltage) });
+ }
+ const metrics = calcMetrics(points);
+ const oracleFillFactor = oracle.y / (testCase.isc * testCase.voc);
+
+ expect(Math.abs(metrics.isc / testCase.isc - 1)).toBeLessThan(1e-10);
+ expect(Math.abs(metrics.voc / testCase.voc - 1)).toBeLessThan(2e-5);
+ expect(Math.abs(metrics.vmp - oracle.x)).toBeLessThan(2 * step);
+ expect(Math.abs(metrics.pmax / oracle.y - 1)).toBeLessThan(2e-4);
+ expect(Math.abs(metrics.ff / oracleFillFactor - 1)).toBeLessThan(2e-4);
+ expect(metrics.quality).toBe("pass");
+ }
+ });
+
+ it("preserves dimensionless metrics under current scaling", () => {
+ const base = [
+ { voltage: 0, rawCurrent: 2 },
+ { voltage: 0.2, rawCurrent: 1.6 },
+ { voltage: 0.5, rawCurrent: 1 },
+ { voltage: 0.8, rawCurrent: 0.4 },
+ { voltage: 1, rawCurrent: 0 },
+ { voltage: 1.1, rawCurrent: -0.2 },
+ ];
+ const scaled = base.map((point) => ({ ...point, rawCurrent: point.rawCurrent * 1e-6 }));
+ const originalMetrics = calcMetrics(base);
+ const scaledMetrics = calcMetrics(scaled);
+
+ expect(scaledMetrics.voc).toBeCloseTo(originalMetrics.voc, 12);
+ expect(scaledMetrics.vmp).toBeCloseTo(originalMetrics.vmp, 12);
+ expect(scaledMetrics.ff).toBeCloseTo(originalMetrics.ff, 12);
+ expect(scaledMetrics.isc / originalMetrics.isc).toBeCloseTo(1e-6, 12);
+ expect(scaledMetrics.pmax / originalMetrics.pmax).toBeCloseTo(1e-6, 12);
+ expect(scaledMetrics.rs / originalMetrics.rs).toBeCloseTo(1e6, 8);
+ expect(scaledMetrics.rsh / originalMetrics.rsh).toBeCloseTo(1e6, 8);
+ });
+});
+
+describe("accuracy validation — censoring and adversarial sweeps", () => {
+ it("withholds derived metrics when Voc is outside the measured range", () => {
+ const metrics = calcMetrics([
+ { voltage: 0, rawCurrent: 1 },
+ { voltage: 0.3, rawCurrent: 0.95 },
+ { voltage: 0.6, rawCurrent: 0.8 },
+ { voltage: 0.9, rawCurrent: 0.5 },
+ ]);
+ expect(metrics.voc).toBe(0.9);
+ expect(metrics.status.voc).toBe("lower-bound");
+ expect(metrics.status.pmax).toBe("provisional");
+ expect(metrics.ff).toBeNull();
+ expect(metrics.rs).toBeNull();
+ expect(metrics.warnings.some((warning) => /lower bound/.test(warning))).toBe(true);
+ });
+
+ it("detects rather than clamps an unphysical fill factor", () => {
+ const metrics = calcMetrics([
+ { voltage: 0, rawCurrent: 1 },
+ { voltage: 0.25, rawCurrent: 8 },
+ { voltage: 0.5, rawCurrent: 10 },
+ { voltage: 1, rawCurrent: 0 },
+ { voltage: 1.1, rawCurrent: -1 },
+ ]);
+ expect(metrics.ff).toBeGreaterThan(1);
+ expect(metrics.status.ff).toBe("unphysical");
+ expect(metrics.quality).toBe("invalid");
+ expect(metrics.errors.some((error) => /physical 0–100/.test(error))).toBe(true);
+ });
+
+ it("withholds Voc-dependent metrics when multiple zero crossings are ambiguous", () => {
+ const metrics = calcMetrics([
+ { voltage: 0, rawCurrent: 1 },
+ { voltage: 0.4, rawCurrent: 0.5 },
+ { voltage: 0.6, rawCurrent: -0.1 },
+ { voltage: 0.8, rawCurrent: 0.2 },
+ { voltage: 1, rawCurrent: -0.2 },
+ ]);
+ expect(metrics.voc).toBeNull();
+ expect(metrics.status.voc).toBe("ambiguous");
+ expect(metrics.ff).toBeNull();
+ expect(metrics.rs).toBeNull();
+ expect(metrics.quality).toBe("invalid");
+ expect(metrics.errors.some((error) => /crosses.*2 times.*ambiguous/.test(error))).toBe(true);
+ });
+
+ it("fails closed when extreme finite inputs overflow derived power", () => {
+ const metrics = calcMetrics([
+ { voltage: 0, rawCurrent: 1e308 },
+ { voltage: 2, rawCurrent: 1e308 },
+ { voltage: 4, rawCurrent: -1e308 },
+ ]);
+ expect(metrics.quality).toBe("invalid");
+ expect(metrics.status.pmax).toBe("overflow");
+ expect(metrics.errors.some((error) => /V·I product overflowed/.test(error))).toBe(true);
+ const rows = metricsToRows(
+ { conditions: ["Extreme"], ivData: { Extreme: [] } },
+ { Extreme: metrics }
+ );
+ expect(rows[1][rows[0].indexOf("Pmax (W)")]).toBe("");
+ expect(computeEfficiency(1e308, 1e-308, 1e-308)).toBeNull();
+ });
+
+ it("averages duplicate voltage samples explicitly and reports the operation", () => {
+ const metrics = calcMetrics([
+ { voltage: 0, rawCurrent: 1 },
+ { voltage: 0.5, rawCurrent: 0.4 },
+ { voltage: 0.5, rawCurrent: 0.6 },
+ { voltage: 1, rawCurrent: 0 },
+ { voltage: 1.1, rawCurrent: -0.1 },
+ ]);
+ expect(metrics.sampleCount).toBe(5);
+ expect(metrics.uniqueVoltageCount).toBe(4);
+ expect(metrics.notes.duplicateVoltages).toBe(1);
+ expect(metrics.pmax).toBeCloseTo(0.25, 12);
+ expect(metrics.warnings.some((warning) => /repeated voltage/.test(warning))).toBe(true);
+ });
+
+ it("uses the samples nearest zero when extrapolating Isc from negative voltage", () => {
+ const metrics = calcMetrics([
+ { voltage: -3, rawCurrent: 10 },
+ { voltage: -2, rawCurrent: 8 },
+ { voltage: -1, rawCurrent: 3 },
+ ]);
+ expect(metrics.isc).toBeCloseTo(-2, 12);
+ expect(metrics.status.isc).toBe("extrapolated");
+ expect(metrics.quality).toBe("invalid");
+ });
+});
+
+describe("workbook and chart integrity", () => {
+ it("preserves physical column positions, uniquifies headers, and never inserts zeros", () => {
+ const parsed = extractIV([
+ ["V", "Cell", "", "Reference", "Cell"],
+ [0, 1, "", 3, 4],
+ [0.5, "", 0.4, 2, 3],
+ [1, -0.1, 0.1, 0.5, 2],
+ [1.5, -0.2, -0.1, -1, -1],
+ ]);
+
+ expect(parsed.conditions).toEqual(["Cell", "Channel 2", "Reference", "Cell (2)"]);
+ expect(parsed.ivData.Cell.map((point) => point.rawCurrent)).toEqual([1, -0.1, -0.2]);
+ expect(parsed.ivData["Channel 2"].map((point) => point.rawCurrent)).toEqual([0.4, 0.1, -0.1]);
+ expect(parsed.ivData.Reference[0].rawCurrent).toBe(3);
+ expect(parsed.ivData["Cell (2)"][0].rawCurrent).toBe(4);
+ expect(parsed.diagnostics.warnings.some((warning) => /no zero values were inserted/.test(warning))).toBe(true);
+ expect(parsed.diagnostics.warnings.some((warning) => /renamed "Cell \(2\)"/.test(warning))).toBe(true);
+ });
+
+ it("rejects channels without three unique voltage setpoints", () => {
+ const parsed = extractIV([
+ ["V", "Repeated", "Valid"],
+ [0, 1, 1],
+ [0, 2, 2],
+ [0, 3, 3],
+ [0.5, "", 2],
+ [1, "", 0],
+ ]);
+ expect(parsed.conditions).toEqual(["Valid"]);
+ expect(parsed.diagnostics.warnings).toContain(
+ "Column 2 (Repeated) was ignored because it contains 3 valid pair(s) across 1 unique voltage(s); at least 3 unique voltages are required."
+ );
+ });
+
+ it("enforces worksheet row and column safety limits", () => {
+ const tooManyRows = Array.from({ length: 250002 }, (_, index) =>
+ index === 0 ? ["V", "I"] : [index, 1]
+ );
+ expect(() => extractIV(tooManyRows)).toThrow(/250,000-data-row safety limit/);
+ const tooWide = [["V"], [0]];
+ tooWide[0].length = 2049;
+ tooWide[1].length = 2049;
+ expect(() => extractIV(tooWide)).toThrow(/2,048-column safety limit/);
+ });
+
+ it("aligns sparse channels by voltage instead of row index", () => {
+ const dataset = {
+ conditions: ["A", "B"],
+ ivData: {
+ A: [
+ { voltage: 0, rawCurrent: 1 },
+ { voltage: 1, rawCurrent: 0.5 },
+ { voltage: 2, rawCurrent: -0.1 },
+ ],
+ B: [
+ { voltage: 0, rawCurrent: 2 },
+ { voltage: 0.5, rawCurrent: 1.5 },
+ { voltage: 0.5, rawCurrent: 1.7 },
+ { voltage: 2, rawCurrent: -0.2 },
+ ],
+ },
+ };
+ const rows = buildAlignedRows(dataset);
+ expect(rows.map((row) => row.voltage)).toEqual([0, 0.5, 1, 2]);
+ expect(rows[1].A).toBeUndefined();
+ expect(rows[1].B).toBeCloseTo(1.6, 12);
+ expect(rows[2].A).toBe(0.5);
+ expect(rows[2].B).toBeUndefined();
+ });
+
+ it("parses BOM, quoted commas, escaped quotes, and embedded newlines", () => {
+ const rows = parseCsv("\ufeffV,\"Cell, A\",\"Note\"\r\n0,1,\"line 1\nline 2\"\r\n1,-0.1,\"a \"\"quote\"\"\"");
+ expect(rows).toEqual([
+ ["V", "Cell, A", "Note"],
+ ["0", "1", "line 1\nline 2"],
+ ["1", "-0.1", 'a "quote"'],
+ ]);
+ });
+
+ it("rejects malformed or excessive CSV input", () => {
+ expect(() => parseCsv('V,"open\n1,2')).toThrow(/unterminated/);
+ expect(() => parseCsv("a,b,c", { maxColumns: 2 })).toThrow(/column safety limit/);
+ expect(() => parseCsv("a\nb", { maxRows: 1 })).toThrow(/row safety limit/);
+ });
+});
+
+describe("export integrity", () => {
+ it("exports status, quality, sample counts, and flags with every metric row", () => {
+ const dataset = {
+ conditions: ["Censored"],
+ ivData: {
+ Censored: [
+ { voltage: 0, rawCurrent: 1 },
+ { voltage: 0.5, rawCurrent: 0.9 },
+ { voltage: 1, rawCurrent: 0.8 },
+ ],
+ },
+ };
+ const metrics = { Censored: calcMetrics(dataset.ivData.Censored) };
+ const rows = metricsToRows(dataset, metrics);
+ const header = rows[0];
+ const data = rows[1];
+ expect(data[header.indexOf("FF (%)")]).toBe("");
+ expect(data[header.indexOf("Voc status")]).toBe("lower-bound");
+ expect(data[header.indexOf("Pmax status")]).toBe("provisional");
+ expect(data[header.indexOf("Quality")]).toBe("review");
+ expect(data[header.indexOf("Valid samples")]).toBe(3);
+ expect(data[header.indexOf("Metric flags")]).toMatch(/FF and Rs are withheld/);
+ expect(data[header.indexOf("Analysis version")]).toBe("4.0.0");
+ expect(data[header.indexOf("Analysis method")]).toBe("piecewise-linear-v4");
+ });
+
+ it("exports signed raw measurements, gaps, and provenance without shifting rows", () => {
+ const dataset = {
+ name: "Sparse measurement",
+ source: { file: "run-17.csv", sheet: "CSV" },
+ diagnostics: { warnings: ["B: skipped one blank cell."] },
+ conditions: ["A", "B"],
+ ivData: {
+ A: [
+ { voltage: 0, rawCurrent: 1 },
+ { voltage: 1, rawCurrent: -0.1 },
+ ],
+ B: [
+ { voltage: 0.5, rawCurrent: 2 },
+ { voltage: 1, rawCurrent: -0.2 },
+ ],
+ },
+ };
+ const raw = rawDataToRows(dataset);
+ expect(raw).toEqual([
+ ["Voltage (V)", "A (A)", "B (A)"],
+ [0, 1, ""],
+ [0.5, "", 2],
+ [1, -0.1, -0.2],
+ ]);
+ const metadata = Object.fromEntries(metadataToRows(dataset).slice(1));
+ expect(metadata["Source file"]).toBe("run-17.csv");
+ expect(metadata["Source sheet"]).toBe("CSV");
+ expect(metadata["Import flags"]).toMatch(/blank cell/);
+ });
+
+ it("round-trips the three-sheet research workbook through the production libraries", async () => {
+ const toCells = (rows) => rows.map((row) => row.map((value) => ({
+ value,
+ type: typeof value === "number" ? Number : String,
+ })));
+ const buffer = await writeExcelFile([
+ { sheet: "Metrics", data: toCells([["Condition", "Pmax (W)"], ["A", 0.25]]) },
+ { sheet: "Raw Data", data: toCells([["Voltage (V)", "A (A)"], [0, 1], [1, 0]]) },
+ { sheet: "Metadata", data: toCells([["Field", "Value"], ["Analysis version", "4.0.0"]]) },
+ ]).toBuffer();
+ const sheets = await readExcelFile(buffer);
+
+ expect(sheets.map(({ sheet }) => sheet)).toEqual(["Metrics", "Raw Data", "Metadata"]);
+ expect(sheets[0].data[1]).toEqual(["A", 0.25]);
+ expect(sheets[1].data[2]).toEqual([1, 0]);
+ expect(sheets[2].data[1]).toEqual(["Analysis version", "4.0.0"]);
+ });
+
+ it("neutralizes spreadsheet formulas in string cells without changing numbers", () => {
+ const csv = rowsToCsv([
+ ["Condition", "Value"],
+ ["=HYPERLINK(\"https://example.invalid\")", -2],
+ ["-2mm", 3],
+ ]);
+ expect(csv).toContain(`"'=HYPERLINK(""https://example.invalid"")"`);
+ expect(csv).toContain("'-2mm,3");
+ expect(csv).toContain(',-2');
+ });
+
+ it("rejects invalid power in efficiency calculations", () => {
+ expect(computeEfficiency(-1, 1, 1000)).toBeNull();
+ expect(computeEfficiency(Infinity, 1, 1000)).toBeNull();
+ });
+
+ it("exports efficiency inputs and marks unphysical efficiency explicitly", () => {
+ const dataset = {
+ conditions: ["Cell"],
+ ivData: {
+ Cell: [
+ { voltage: 0, rawCurrent: 2 },
+ { voltage: 0.5, rawCurrent: 1 },
+ { voltage: 1, rawCurrent: 0 },
+ ],
+ },
+ };
+ const metrics = { Cell: calcMetrics(dataset.ivData.Cell) };
+ const rows = metricsToRows(dataset, metrics, { Cell: 125 }, {
+ cellAreaCm2: 0.01,
+ irradianceWm2: 1000,
+ });
+ const header = rows[0];
+ const data = rows[1];
+ expect(data[header.indexOf("Efficiency status")]).toBe("unphysical");
+ expect(data[header.indexOf("Cell area (cm2)")]).toBe(0.01);
+ expect(data[header.indexOf("Irradiance (W/m2)")]).toBe(1000);
+ expect(data[header.indexOf("Metric flags")]).toMatch(/above the physical 100 % limit/);
+ });
+});
diff --git a/tests/e2e.smoke.mjs b/tests/e2e.smoke.mjs
index 61593ac..5ec618f 100644
--- a/tests/e2e.smoke.mjs
+++ b/tests/e2e.smoke.mjs
@@ -7,18 +7,23 @@
* - the deterministic assistant answers from the dataset.
*
* Run with: npm run test:e2e
- * Requires a Chromium that Playwright can launch. If none is available the test
- * SKIPS (exit 0) rather than failing, so it never blocks a CI that hasn't
- * provisioned browsers.
+ * Requires a Chromium that Playwright can launch. A missing browser skips only
+ * for local development; CI treats it as a hard failure.
*/
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
import { resolve } from "node:path";
+import readExcelFile from "read-excel-file/node";
+import writeExcelFile from "write-excel-file/node";
let chromium;
try {
({ chromium } = await import("playwright"));
-} catch {
- console.log("⚠ playwright not installed — skipping e2e smoke test.");
+} catch (error) {
+ if (process.env.CI === "true") {
+ console.error("✗ Playwright is required in CI:", error.message);
+ process.exit(1);
+ }
+ console.log("⚠ playwright not installed — skipping local e2e smoke test.");
process.exit(0);
}
@@ -39,7 +44,11 @@ for (const executablePath of [undefined, ...fallbacks]) {
break;
} catch (e) {
if (executablePath === fallbacks[fallbacks.length - 1] || fallbacks.length === 0) {
- console.log("⚠ no launchable Chromium (" + e.message.split("\n")[0] + ") — skipping e2e smoke test.");
+ if (process.env.CI === "true") {
+ console.error("✗ no launchable Chromium in CI (" + e.message.split("\n")[0] + ")");
+ process.exit(1);
+ }
+ console.log("⚠ no launchable Chromium (" + e.message.split("\n")[0] + ") — skipping local e2e smoke test.");
process.exit(0);
}
}
@@ -47,7 +56,7 @@ for (const executablePath of [undefined, ...fallbacks]) {
const errors = [];
try {
- const page = await browser.newPage();
+ const page = await browser.newPage({ viewport: { width: 1440, height: 1000 } });
page.on("console", (m) => { if (m.type() === "error" && !m.text().includes("ERR_")) errors.push("console: " + m.text()); });
page.on("pageerror", (e) => errors.push("pageerror: " + e.message));
@@ -60,8 +69,9 @@ try {
const closeWelcome = page.getByRole("button", { name: "Start analysing" });
if (await closeWelcome.count()) await closeWelcome.first().click();
await page.waitForTimeout(400);
- const dismiss = page.getByRole("button", { name: "Dismiss" });
- if (await dismiss.count()) await dismiss.first().click();
+ const dismissTour = page.getByRole("button", { name: "Dismiss guided tour", exact: true });
+ await dismissTour.click();
+ await dismissTour.waitFor({ state: "detached" });
// Visit every visualization tab (including the synced dual view).
await page.getByRole("button", { name: "Visualizations", exact: true }).click();
@@ -70,6 +80,10 @@ try {
await page.getByRole("button", { name: tab, exact: true }).click();
await page.waitForTimeout(300);
}
+ const chartIntegrity = await page.evaluate(() => {
+ const paths = [...document.querySelectorAll(".recharts-line-curve, .recharts-area-curve")];
+ return paths.length > 0 && paths.every((path) => !/NaN|Infinity/.test(path.getAttribute("d") || ""));
+ });
// Metrics + efficiency.
await page.getByRole("button", { name: "Metrics & Export", exact: true }).click();
@@ -82,7 +96,18 @@ try {
await page.fill('input[placeholder="0.01"]', "0.01");
await page.fill('input[placeholder="1000"]', "1000");
await page.waitForTimeout(300);
- const hasEff = await page.evaluate(() => document.body.innerText.includes("η"));
+ const hasEff = await page.evaluate(() => {
+ const table = [...document.querySelectorAll("table")].find((candidate) =>
+ candidate.innerText.includes("CONDITION") && candidate.innerText.includes("FF")
+ );
+ if (!table) return false;
+ const headers = [...table.querySelectorAll("th")].map((cell) => cell.innerText.trim());
+ const efficiencyIndex = headers.findIndex((header) => header.includes("η (%)"));
+ if (efficiencyIndex < 0) return false;
+ const values = [...table.querySelectorAll("tbody tr")]
+ .map((row) => Number(row.querySelectorAll("td")[efficiencyIndex]?.innerText));
+ return values.length > 0 && values.every((value) => Number.isFinite(value) && value > 0);
+ });
// Assistant.
await page.getByRole("button", { name: /Lab Assistant/ }).click();
@@ -93,18 +118,108 @@ try {
const ffOk = Array.isArray(ffValues) && ffValues.length > 0 && ffValues.every((f) => f > 0 && f < 100);
+ // Import a deliberately sparse CSV. Each channel omits a different voltage,
+ // which catches the historical row-index alignment bug in the real UI.
+ await page.getByRole("button", { name: "Import Data", exact: true }).click();
+ const sparseCsv = [
+ "Voltage(V),Cell A,Cell B",
+ "0,1,2",
+ "0.5,,1.5",
+ "1,0.5,",
+ "1.5,0.1,0.2",
+ "2,-0.2,-0.1",
+ ].join("\n");
+ await page.locator('input[type="file"]').setInputFiles({
+ name: "sparse_iv.csv",
+ mimeType: "text/csv",
+ buffer: Buffer.from(sparseCsv),
+ });
+ await page.getByText("sparse_iv (CSV)", { exact: false }).first().waitFor();
+ const rawDataTable = page.getByRole("table", { name: "Raw I-V measurements", exact: true });
+ await rawDataTable.waitFor();
+ await rawDataTable.getByRole("columnheader", { name: "Cell A", exact: true }).waitFor();
+ const sparseAlignment = await rawDataTable.evaluate((table) => {
+ const rows = [...table.querySelectorAll("tbody tr")].map((row) =>
+ [...row.querySelectorAll("td")].map((cell) => cell.innerText.trim())
+ );
+ const atHalfVolt = rows.find((row) => row[0] === "0.50");
+ const atOneVolt = rows.find((row) => row[0] === "1.00");
+ return {
+ ok: atHalfVolt?.[1] === "—" && atHalfVolt?.[2] === "1.500e+0" &&
+ atOneVolt?.[1] === "5.000e-1" && atOneVolt?.[2] === "—",
+ rows,
+ };
+ });
+ const sparseAlignmentOk = sparseAlignment.ok;
+ await page.getByRole("button", { name: "Metrics & Export", exact: true }).click();
+ await page.getByText(/skipped 1 row\(s\).*no zero values were inserted/i).first().waitFor();
+
+ const csvDownloadPromise = page.waitForEvent("download");
+ await page.getByRole("button", { name: "EXPORT CSV", exact: true }).click();
+ const csvDownload = await csvDownloadPromise;
+ const csvText = readFileSync(await csvDownload.path(), "utf8");
+ const csvExportOk = csvDownload.suggestedFilename() === "solavin_iv_metrics.csv" &&
+ csvText.includes("Analysis version") &&
+ csvText.includes("piecewise-linear-v4") &&
+ csvText.includes("sparse_iv.csv") &&
+ csvText.includes("Import flags");
+
+ const xlsxDownloadPromise = page.waitForEvent("download");
+ await page.getByRole("button", { name: "EXPORT XLSX", exact: true }).click();
+ const xlsxDownload = await xlsxDownloadPromise;
+ const exportedWorkbook = await readExcelFile(await xlsxDownload.path());
+ const exportedMetadata = Object.fromEntries(
+ exportedWorkbook.find(({ sheet }) => sheet === "Metadata").data.slice(1)
+ );
+ const xlsxExportOk = xlsxDownload.suggestedFilename() === "solavin_iv_analysis.xlsx" &&
+ exportedWorkbook.map(({ sheet }) => sheet).join("|") === "Metrics|Raw Data|Metadata" &&
+ exportedMetadata["Solavin analysis version"] === "4.0.0" &&
+ exportedMetadata["Analysis method"] === "piecewise-linear-v4" &&
+ exportedMetadata["Source file"] === "sparse_iv.csv" &&
+ exportedMetadata["Cell area (cm2)"] === 0.01 &&
+ exportedMetadata["Irradiance (W/m2)"] === 1000;
+
+ // Exercise the browser-side XLSX reader and multi-sheet picker with a
+ // workbook generated independently in Node.
+ await page.getByRole("button", { name: "Import Data", exact: true }).click();
+ const workbookBuffer = await writeExcelFile([
+ {
+ sheet: "Run A",
+ data: [["Voltage (V)", "Cell X"], [0, 1], [0.5, 0.6], [1, 0], [1.1, -0.1]],
+ },
+ {
+ sheet: "Run B",
+ data: [["Voltage (V)", "Cell Y"], [0, 2], [0.5, 1.2], [1, 0], [1.1, -0.2]],
+ },
+ ]).toBuffer();
+ await page.locator('input[type="file"]').setInputFiles({
+ name: "browser_fixture.xlsx",
+ mimeType: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+ buffer: workbookBuffer,
+ });
+ await page.getByText("Select Sheet", { exact: true }).waitFor();
+ await page.getByRole("button", { name: "Run B", exact: true }).click();
+ const xlsxImport = page.getByText("browser_fixture (Run B)", { exact: false }).first();
+ await xlsxImport.waitFor();
+ const xlsxImportOk = await xlsxImport.isVisible();
+
const fail = [];
if (errors.length) fail.push("runtime errors: " + JSON.stringify(errors));
if (!welcomeShown) fail.push("orientation (welcome) panel did not appear on first load");
if (!ffOk) fail.push("fill factors not all in (0,100)%: " + JSON.stringify(ffValues));
if (!hasEff) fail.push("efficiency column missing");
if (!assistantOk) fail.push("assistant did not answer fill-factor query");
+ if (!chartIntegrity) fail.push("chart SVG paths were missing or contained NaN/Infinity");
+ if (!sparseAlignmentOk) fail.push("sparse channels were not preserved at their correct voltages; observed rows: " + JSON.stringify(sparseAlignment.rows));
+ if (!csvExportOk) fail.push("CSV export did not produce the expected download");
+ if (!xlsxExportOk) fail.push("XLSX export did not produce the expected download");
+ if (!xlsxImportOk) fail.push("browser XLSX import or multi-sheet selection failed");
if (fail.length) {
console.error("✗ e2e smoke test FAILED:\n - " + fail.join("\n - "));
process.exitCode = 1;
} else {
- console.log("✓ e2e smoke test passed — FF values:", ffValues.map((f) => f.toFixed(1)).join(", "), "%");
+ console.log("✓ e2e passed — charts, sparse CSV + multi-sheet XLSX import, assistant, efficiency, CSV/XLSX exports; FF:", ffValues.map((f) => f.toFixed(1)).join(", "), "%");
}
} finally {
await browser.close();
diff --git a/vite.config.js b/vite.config.js
index 828d8d2..f772e2f 100644
--- a/vite.config.js
+++ b/vite.config.js
@@ -13,5 +13,16 @@ export default defineConfig({
test: {
environment: "node",
include: ["src/**/*.test.js"],
+ coverage: {
+ provider: "v8",
+ reporter: ["text", "json-summary", "html"],
+ include: ["src/lib/ivAnalysis.js"],
+ thresholds: {
+ statements: 90,
+ branches: 80,
+ functions: 90,
+ lines: 90,
+ },
+ },
},
});