Reference: Glossary, File Formats & Troubleshooting

The loss cascade, line by line

Every pvSpline simulation produces a single ordered loss cascade: the chain that turns the sunlight arriving on your modules into the energy delivered at the meter. It is what the Sankey loss diagram (Charts, Heatmaps & Tables) and the report loss page (Reporting & Export) draw, and it is the same order in the PDF, the CSV export and the on-screen chart. The order is canonical and fixed — irradiance first, grid connection last — so an auditor can match it line for line against a PVsyst loss diagram.

A few conventions make the diagram readable:

• Most lines are losses: the energy shrinks as you go down. A handful are gains (a credit, drawn as a positive step): transposition, bifacial rear-side, LCPV concentration and the battery outage-recovery credit — and temperature, on a site where cold hours outweigh hot ones.

• Some lines are ghost entries. The physics solver already subtracted that energy upstream (for example far/horizon shading is baked into the plane-of-array total before the cells ever see it); the ghost line surfaces the hidden amount for the diagram without deducting it twice.

• A line only appears when it is non-zero for your project. A fixed-tilt rooftop with no trackers, no optimizers and no transformer shows perhaps a dozen lines; a large ground-mount with trackers, combiners, MV/HV transformers and a weak grid shows most of them.

• On the diagram a label may carry a qualifier that says how its number was obtained — (hourly integrated), (computed), (scheduled), (STC, local), (3-D bake) and the like — after the names listed below.

• Each line carries a provenance tag (see Reporting & Export) recording where its number came from: a value you typed, a PVGIS-attested breakdown for your exact site, an Open-Meteo-computed weather loss, or an hour-by-hour integration over your sized bill of materials.

The table below lists every line in cascade order, grouped by the stage it belongs to.

File formats

The project file: .pvspline.json

A pvSpline project is a single self-contained JSON document. It stores everything about the project: name and client details, the site (latitude, longitude, altitude, time zone, country), every array polygon (tilt, azimuth, ground coverage, albedo, tracker type, the panel it uses, its peak power), the tariff structure, capacity subscription, battery configuration, time-of-use windows, EV sessions, export-limit schedules, and the batch study from the Batch tab — its scenarios, results and chart axes — that the report's comparison page is printed from.

Every project file carries a top-level schema integer. The current version is 31. pvSpline handles version skew automatically:

• Older files are migrated up one version at a time when you open them, so an old project keeps working after you update the app. Files below the supported floor (schemas 1–4) are refused — open them in an older release and re-save to upgrade.

• Newer files (a file written by a release newer than the engine answering) open with a soft warning and read only the fields that engine understands. It will not write such a project back out at the older version — it refuses rather than silently drop the newer data, so a round trip through an older engine cannot quietly damage the file.

• A missing or zero schema is rejected outright.

Imported component datasheets: .PAN / .OND / .BTR / .PMP

pvSpline reads the native PVsyst component datasheet formats directly, so your existing library imports with zero re-entry (The Component Catalogue) — in the web app, by anyone holding the Manager or Admin role in your company:

• .PAN — a PV module: electrical parameters, the temperature coefficients, the maximum system voltage it is certified for (IEC and UL), and the measured incidence-angle (IAM) and low-light curves.

• .OND — an inverter: nameplate, MPPT window, and the efficiency curve (Euro/CEC or the full imported curve).

• .BTR — a battery: capacity and electrical characteristics.

• .PMP — a solar-pump curve (head versus flow), for the water-pumping system type.

These files are Windows-1252 encoded and use PVsyst's PVObject_ section syntax; pvSpline tolerates unknown keys. Importing brings the component into your catalogue — it does not import a whole PVsyst project (.PRJ) or variant.

What you can import in the browser

Every import is an ordinary file picker: click the button, pick a file from your own computer, and the app reads it. Some files are parsed in the browser and never leave it; the rest are sent to the engine, which parses them and hands back the result. Nothing is stored server-side except a cloud upload used to carry a large file to the engine (see below).

How large a file you can import

Every file picker checks the size before it reads anything, and refuses an oversized file by name with both numbers: what your file is, and what the ceiling is. The ceiling is not arbitrary — it is the real limit of whatever would otherwise have refused the upload, so the app never turns away a file the platform would have taken.

Exports: PDF, CSV, XLSX, JSON, SVG, PNG

Everything you export arrives as an ordinary browser download, saved wherever your browser puts downloads. The engine renders it and hands the bytes back; nothing is written on your disk without you.

• PDF — the branded client report from the report workspace on Results (/results, Reporting & Export): themed cover with your logo and the verification QR code (Report verification), a plan of your arrays over orthophoto imagery where it is available, the single-line diagram, the charts you ticked at high resolution — the Sankey loss diagram among them — and the financial projection with its performance footer. It is written in the interface language — for a cloud run, the one the page used when the run started. Its other tabs export the tender dossier, always in French, the permit package and the Consuel technical file.

• XLSX — the financial projection as a one-sheet Excel workbook (the table, its summary block and the column legend) and the bill of materials, both from Results.

• CSV — the bill of materials from Results, the scenario board from Batch (Export CSV…).

• PNG — any chart of a finished run, rendered server-side at report resolution (Charts, Heatmaps & Tables).

• SVG — the one-line diagram, from the menu beside Download PDF on Results or the canvas menu of Diagram (Exporting the diagram and the bill of materials). The drawing is also exportable as a PDF. Both are drawn in the interface language.

• JSON — the working project as a portable file (Project), your preferences (the account page), and a report theme.

Tariff catalogue files (.yaml)

Utility-rate plans are small YAML files, one tariff per file. They ship with the catalogue, and you can add your own from the Catalogue view's Tariffs tab (/catalogue). They carry the provider and plan name, country/currency, validity dates, the buy mode (flat, HP/HC, seasonal HP/HC, hourly CSV or EDF Tempo), the per-period rates, the network/subscription charges and the surplus feed-in tariff. Applying a catalogue tariff to a project is copy-on-apply: the values land on the project's own tariff inputs — the Granularity of the GRID PRICING card included, when the file sets one — and they are not linked. Rates in these files are in cents per kWh, not €/kWh: a file's 21.46 shows as 0.2146 on the project's rate fields.

Glossary of terms & acronyms

Keyboard & mouse shortcuts

pvSpline is a point-and-click application: nearly everything is a button on the view you are in, and no shortcut is the only way to reach an action. The bindings below are the ones that exist. Everywhere it says Ctrl, macOS uses Cmd.

Anywhere in the app

Three shortcuts are bound to the whole window, whichever view you are on.

They deliberately stand down in four situations, so they never fire when you meant something else:

• while the cursor is in a text box, number field, dropdown or rich-text area — Ctrl+Z then belongs to the field you are typing in;

• while the licence agreement is on screen, which owns the whole window until you accept it;

• while the report theme editor or the permit dialog is open — those take the keyboard over, with their own bindings (below);

• whenever Alt is also held.

Map (/map)

Catalogue (/catalogue)

One-line diagram (/diagram)

The drawing takes the keyboard once you click into it.

Report theme editor (/results)

While the theme editor is open it owns the keyboard, and the global shortcuts above stand down.

Elsewhere

Where the browser's own shortcuts fit in

pvSpline claims very little of the keyboard, so almost every browser shortcut still works as you expect. That is a feature, not an oversight:

• Reload (F5 / Ctrl+R) reloads the app. If the working project has unsaved changes, the browser's own “leave this site?” prompt appears first — pvSpline asks it to. Answer stay if you did not mean to.

• Back and forward move between views, because every view has its own address. Going back out of a results page does not cancel the run behind it.

• Find (Ctrl+F) is the browser's, untouched. It searches what is rendered; to search a catalogue or your projects, use the view's own search box, which searches everything, not just the visible rows.

• Print (Ctrl+P) is the browser's. For a client deliverable use the report's own print action instead — it prints the rendered report rather than the app window. If your browser blocks the window it opens, allow pop-ups for the site, or export the PDF and print that.

• Save page (Ctrl+S) is the browser's — except inside the report theme editor, which uses it to save the theme. To save a project to your account, use Save on Project.

• Zoom (Ctrl++ / Ctrl+-) scales the whole app. The map, the diagram and the report preview also have their own zoom, which is the one to reach for.

• Full screen (F11) belongs to the browser and cannot be reassigned; the video player offers F for its own full-screen instead.

Troubleshooting & FAQ

Each entry below is a symptom, the cause behind it, and the fix.

Weather or consumption data will not load

Symptom. A fetch reports a failure, or a run stops to say it is fetching weather and never finishes.

Cause and fix.

• No site set. The fetch says so: set the latitude and longitude on Map (The Map & Site Design Tab) first. Nothing can be fetched for a site at 0, 0.

• Already fetched, nothing happening. Weather is fetched automatically — when an array is drawn or edited, before the next run, and again whenever the site moves — and only what the project lacks is downloaded, so there is often nothing to press. A project that already has weather offers Refresh weather data instead, which re-downloads everything on demand.

• The Open-Meteo badge stays at Open-Meteo data not embedded. The weather-history service did not answer. The fetch still embeds the PVGIS irradiance, so runs go ahead, but Soiling and Snow on Auto (weather) cannot follow the weather and keep the project's own figures, and the 3-D view's Real weather reports Weather unavailable: …. No other weather service stands in for it. Press Refresh weather data on Production later to try again: nothing retries on its own until the site moves.

• The first fetch for a site is slow. The weather history of a site that has not been fetched before takes noticeably longer to arrive the first time; later fetches for the same site come back quicker. A run started meanwhile waits with Fetching weather data for the site first — the run starts as soon as it lands… — let it finish.

• Enedis consumption will not pull. Metered-load retrieval is French and needs an authorised delivery point: the 14-digit PRM belongs to the saved project and comes from the customer's authorisation, so it cannot be typed in here. If the project has none, start the consent flow from the same card (The Consumption Tab).

• A delivery point that downloaded before now refuses with No Enedis authorization is in force for this PRM…. The customer's authorisation has most likely expired — it runs for the duration stated on the form the customer signed, twelve months by default — or been revoked; the same message covers Enedis access switched off for your account, which someone with the Manager role in your company can switch on. A project saved to your account keeps the metered series only while the authorisation is in force: once it ends, the series is removed from every saved version, the run's Warnings card says the delivery point has no embedded consumption series, and only a new authorisation signed by the customer lets you download it again (When your client's authorisation expires).

A run failed, or you want to stop one

Symptom. The report's place on Results reads This job failed: with a message, or a run you no longer want is on its way.

Cause and fix.

• Read the message first — it comes from the engine and usually names the input at fault. Then run it again: the check that starts every run lists, under Run the project, exactly what is missing or out of range, and stops the run before anything is computed.

• A failed cloud run is charged the engine time it used. Fixing the input and running again spends the new run on top, so read the failed run's Warnings card before resubmitting it. An error the check catches stops a run before it is submitted, so it costs nothing.

• A run is not withdrawn from Results. Once the engine has picked a job up it cannot be interrupted, so let it finish and run again. A cloud run still queued is cancelled from the Cloud runs list on the account page (Cloud runs: the job history).

• Jobs disappearing from Choose a job. The list keeps a bounded number of recent jobs per session. A result you need to keep is already in your run history on Account.

• Some rows of a batch come back failed. Step 4 lists them under Scenarios the engine did not run:. Each swaps in a part that neither the project, the engine's catalogue nor your company's shared components hold, so the engine refuses to run it rather than score your own part under that part's name. The run's Log names the part: add it to your company's catalogue (Manager or Admin role, The Component Catalogue) or pick another, then run the batch again (Batch Simulation & Scenario Sweeps).

A cloud run stays queued

Symptom. A row in Cloud runs keeps reading Queued — pickup typically ≤ 5 s well past five seconds — or, on the free plan, Queued — on the free plan, runs start once no paying customer’s run is waiting.

Cause. Every worker is busy. The workers are shared by all pvSpline companies and take turns between them: another company's long backlog does not all go ahead of you, only its next job at each turn. Within your own company the oldest job starts first, so runs and batches your colleagues — or a script or an AI assistant working for your company — queued earlier start before yours. On the free plan, paying customers' runs go first, even ones queued after yours: your run starts only once none is waiting, and a batch or optimization under way can be stopped to make room for one — its row then reads Queued again — stopped to make room for a paying customer’s run (free plan); it starts over once a worker is free (Paying customers' work goes first).

Fix. Wait: the row turns Running on its own, and the time spent queued is never charged — the drawer's Queue figure counts it apart from the Engine time. To see what your company has waiting, pick the Active chip in Cloud runs (Cloud runs: the job history), and cancel the queued runs you no longer need: a run cancelled before pickup costs nothing. On the free plan, subscribing lifts the wait at once: your company's runs, those already queued included, then go first like any paying customer's.

The cloud refuses to queue a run

Symptom. Pressing Run produces a message instead of a job, mentioning an allowance or a subscription.

Cause. Cloud compute is metered — per member on a subscription, per company on the free plan — and there are several independent meters:

• your monthly simulation allowance is used up — the run was not queued — your engine-time allowance is spent. On a subscription it is your own, not shared with colleagues; on the free plan it is the company's, so a colleague's runs count too. It resets monthly.

• A message that your monthly cloud API allowance is used up — the cloud API meter, which every plan caps. Until it renews on the 1st, saves to your account and other cloud work are refused as well.

• your company's subscription is inactive — cloud runs are paused — a billing state, not a quota.

• Your plan does not include 3-D streaming or Your monthly tile-build allowance is used up — the 3-D meters, which are separate from engine time.

Fix. Open the Usage section of Account (/account/usage): it shows what is left of each allowance and the date it resets, and Advanced mode adds every meter, with what you have spent.

An upload is refused because the file is too large

Symptom. Picking a file produces a refusal naming the file, its size and a limit, before anything is read.

Cause. Every import has a ceiling, and for anything the engine parses it is 25 MB per file through the cloud (File formats).

Fix. For a picture, resize or re-compress it first — the app shrinks images for the report, but the browser has to decode the original at full size before it can.

A different refusal, Your monthly import allowance is used up, is not about one file: in the cloud, every file large enough to be uploaded counts against a monthly allowance — your own on a subscription, your company's on the free plan — shown in the File imports meter on Account. It resets at the start of the next month.

The 3-D view will not start, or the picture is poor

Symptom. Start streaming fails, or the session runs but looks soft or stutters.

Cause and fix. The 3-D view is a rendering session run for you in the cloud and streamed to the tab, so the failures are about entitlement, capacity and bandwidth rather than your graphics card:

• Sign in to your cloud account to start a streaming session — it is not available signed out.

• Your plan does not include 3-D streaming — an entitlement, not a quota. Every plan carries a streaming allowance, the free plan too, so this means your account has no active plan (Your Account, Team & Cloud Runs).

• Your monthly 3-D streaming allowance is used up — the 3-D streaming meter on Account. A session starts only with at least 60 s left; if the allowance runs out mid-session the stream stops, and only the seconds actually streamed are charged.

• Every 3-D server is busy right now. Try again in a few minutes — on the free plan, a session starts only when no paying customer needs the server. — capacity, not your account: every 3-D server is in use, and as paying customers come first, a free-plan session starts only when a server is free and no paying customer needs it (Paying customers' work goes first). Try again a few minutes later.

• 3-D streaming is not enabled on this deployment or The streaming player is not installed on this deployment — nothing you can fix from the app; ask whoever runs the deployment.

• Soft or stuttering picture. The stream adapts to your connection. Lower the Quality setting, close other heavy tabs, and prefer a wired connection — the renderer is not the bottleneck, the link is.

The results do not match the project on screen

Symptom. A results view carries a Stale badge, or the numbers do not reflect an edit you just made.

Cause. Running is explicit: editing the project does not re-run it. The badge appears as soon as what is on screen has drifted from the run being displayed, and its wording names what drifted: Stale — the project changed since this run.

Fix. Press Run the project, right before the badge on Results, which submits the current project and takes you to the new result.

The Results icon is red

Symptom. The Results entry of the navigation rail is red, and its tooltip lists Calculation: The calculation has not been run — sometimes while Results still shows a run.

Cause. The flag speaks for the project open in this tab: this browser knows of no successful run of it. The run on screen, if there is one, is the newest of your session and can belong to the project you had open before. A failed run does not count, and neither does a run made somewhere this browser has not seen — another browser or computer, a colleague, an AI assistant or a script.

Fix. Run the project (Run the project, or Ctrl+Enter from any view). If a cloud run of it already exists that you may open — your own, or any of the company's with the Manager role — View result on its row in Cloud runs (Cloud runs: the job history) clears the flag without spending another run.

A project will not open

Symptom. Picking a .pvspline.json file reports Could not read the selected file, or the project opens but the editing cards say the working project is not valid JSON.

Cause and fix.

• It is not valid JSON. Something truncated or edited the file. Open it in a text editor and confirm it parses, and that it has a top-level schema number.

• It is too old. Files below the supported floor (schemas 1–4) are refused outright. Open such a file in an older pvSpline release and re-save it to bring it forward.

• It is newer than the engine answering. The engine reads only the fields it understands and warns; it will not save the project back down to the older format.

A component datasheet will not import

• .PAN/.OND/.BTR/.PMP files are Windows-1252 encoded; one re-saved as UTF-8, or truncated by a mail gateway, may not parse. Re-export it from PVsyst and import the original bytes.

• You can import a component, not a whole PVsyst project or variant — there is no .PRJ importer.

• If the file is large, check the ceiling above before blaming the file.

• On the Diagram tab the inverter loaded, but it is not in the catalogue. Loading a .OND into an inverter row works for every role, but only the Manager or Admin role also files the device in your company's Inverters catalogue; with the User role the row is filled and nothing more. With the role, The inverter was loaded, but could not be added to the catalogue: … means the row is fine and only the catalogue copy failed — import the file again from the Inverters category of Catalogue.

The report will not print or export

• “No completed run yet.” The study report is drawn from a finished run: pick one at the top of the Results tab, or run the project with Run the project. The town-hall permit and the Consuel dossier need no run.

• “No project is loaded.” The report is guarded on the project, not just the run — open or create one.

• The print window never appears. Your browser blocked the pop-up. Allow pop-ups for the site, or export the PDF and print it from your own viewer.

• The export runs a simulation first. There was no finished run to export, so the app produces one (The report needs a fresh simulation — running the current project…) and exports its report. If that run fails, the message says why: fix what it names and export again.

• The verifier finds no code. Only a report the cloud signed carries one: a cloud run computed before reports were sealed, and a run an AI assistant queued, carry none — run the project again for a report that does. Then drop the PDF itself on the checker rather than a picture of its cover: it reads the file's fingerprint and its seal. A photograph too blurred to read is answered No QR code detected in the image. Try a sharper photo, or drop the PDF. (Report verification).

• The batch-study page is missing. The page prints from the batch study stored in the project the run was computed from, so a run made before the batch has none, and the report has no page for it. Re-run the project, then export — and check that the page's tick box in the chart list is ticked (Batch study — scenario comparison).

The numbers differ from PVsyst

Symptom. A PVsyst study of the same site and the same hardware gives a different annual yield.

Cause. Almost always an input difference rather than a physics difference, and the loss cascade is built to make that visible: it is laid out in PVsyst's own order, and the inverter losses reconcile line for line with the two variable sets PVsyst exports (The loss cascade, line by line).

Fix. Put the two loss diagrams side by side and walk down them. The lines that usually differ are:

• Near shading — pvSpline reports mutual row shading as separate beam, diffuse and electrical lines, and splits vegetation out of the beam line when a 3-D bake saw a canopy. PVsyst rolls all of that into its 3-D scene, so compare the sum, not a single row.

• Soiling, snow and horizon — pvSpline computes these from real weather and the site's own horizon where it can, instead of a typed percentage. Check what each model produced against the constant the other study assumed.

• DC ohmic — computed from your sized cable runs when the project has a bill of materials, rather than a flat percentage.

• The inverter — with no inverter in the electrical design, conversion is a flat loss with no clipping and the yield reads a few percent high; the generic starter inverter that Create initial design places has no datasheet efficiency. The Warnings card on Results says when either applies. Put the PVsyst variant's own inverter on the Diagram tab before comparing (The starter inverter).

• The reference year — confirm both studies use the same weather source and the same probability of exceedance (a P50 median against a P90 lender case will never agree). A pvSpline project is computed at P90 unless you pick another percentile, and the Production tiles and the loss diagram's kWh show that figure — the tiles say so (Annual production · P90) — while a PVsyst annual yield is the P50. Compare it with the P50 segment of Probabilistic production (Probabilistic production (P50/P75/P90/P99)), or pick P50 and run again; the loss percentages are the same at every percentile.

Field reference

This appendix has no editable panel of its own; its “fields” are the entries of the files pvSpline reads and writes. The tables below let you read or hand-author a project, site or tariff file. Each row gives the key, its type and unit, its default, and its meaning. (For the on-screen controls that set these values, see the chapters cross-referenced in each subsection.)

Project file — top-level keys

site sub-object

See The Project Tab and The Map & Site Design Tab for the controls that set these.

polygons array (one per array zone)

See The Map & Site Design Tab and Running a Simulation & the Production Tab.

tariffs sub-object (4-period buy rates)

See Preferences, Tariffs & Theming. Missing keys default to 0.0 (no revenue / no cost). Which of the four a run bills follows the Granularity of the CONSUMPTION RATES card: under Flat rate every hour bills at hphTarif, under Peak / Off-peak summer bills at the winter pair, and under the From an hourly CSV source the hourly curve prices every hour — or, with no curve loaded, the four rates by season and peak hours, which a run warns about. A rawValues cell holding the same rate (tarif_hph … tarif_hce, in c€/kWh) takes precedence over these keys.

capacityCharge sub-object

The capacity-subscription block, billed as far as the Granularity of the GRID PRICING card allows (rawValues.tarification_reseau_mode): 0 (None) bills none of it, 1 (Subscription) bills puissanceSouscriteKva × prixKvaMois but not prixDepassementKvah, and 2 (TURPE + peak-shaving), 3 (Net metering) or a file that stores no level bill all of it. All-zero means “no capacity charge”. A rawValues cell holding the same figure takes precedence over these keys. See Preferences, Tariffs & Theming.

battery sub-object

Physical and virtual (cloud-bank) storage. All-zero = no battery. See Storage, EV & Specialized Systems.

Tariff catalogue YAML

One tariff per file. All fields optional; “absent” stays distinct from “explicitly 0”. Rates are in cents/kWh.