panel-modeler #
panel-modeler estimates photovoltaic panel output over time using a PVWatts-style
calculation and exponential panel degradation. It provides both a CSV command-line
interface and a Qt 6 desktop GUI.
The GUI can retrieve annual climate values from a location entered as coordinates or an address. It also includes a small JSON panel database that can be replaced with a self-hosted HTTP copy.
Requirements #
- C++23 compiler; Clang is required by the Meson configuration
- Meson 1.0 or newer
- Ninja
moldon Linux; macOS uses the system linker because Apple Clang does not accept-fuse-ld=mold- Qt 6 for the GUI and network features
On macOS with Homebrew:
brew install meson ninja qt
On Linux with Homebrew, install the required compiler and linker too:
brew install llvm mold meson ninja qt
Qt is optional at configure time. If it is not available, the CSV CLI and simulation
core still build. To require or disable Qt explicitly, use -Dqt=enabled or
-Dqt=disabled.
Build #
meson setup builddir --native-file clang.ini
meson compile -C builddir
The executables are created at:
builddir/src/panel-modeler
builddir/src/panel-modeler-gui
To start over:
rm -rf builddir
meson setup builddir --native-file clang.ini
Install #
Meson installs both executables, the bundled panel database, and project Documentation:
meson install -C builddir
Use a different prefix during setup if desired:
meson setup builddir --native-file clang.ini --prefix="$HOME/.local"
meson compile -C builddir
meson install -C builddir
The installed layout is approximately:
<prefix>/bin/panel-modeler
<prefix>/bin/panel-modeler-gui
<prefix>/share/panel-modeler/panels.json
<prefix>/share/bash-completion/completions/panel-modeler.bash
<prefix>/share/zsh/site-functions/_panel-modeler
<prefix>/share/fish/vendor_completions.d/panel-modeler.fish
<prefix>/share/icons/hicolor/scalable/apps/panel-modeler.svg
<prefix>/share/doc/panel-modeler/README.md
<prefix>/share/doc/panel-modeler/LICENSE
On Linux, Meson also installs a desktop launcher at
<prefix>/share/applications/panel-modeler.desktop. It launches the Qt GUI from the
application menu.
Shell completions are installed for Bash, Zsh, and Fish. The installed files are
picked up automatically by standard system-wide shell completion setups; for a custom
prefix, add the corresponding completion directory under <prefix>/share to your
shell's completion search path.
To stage an install without modifying the system:
DESTDIR=/tmp/panel-modeler-install meson install -C builddir
GUI #
Start the GUI with:
./builddir/src/panel-modeler-gui
The GUI supports:
- Address geocoding or direct latitude/longitude entry
- Climate lookup and editable irradiance/temperature values
- Adding panels manually or selecting them from the panel database
- Setting the number of identical panels in each array
- Importing the existing input CSV format
- Running the simulation with a results table and line chart
- Exporting results in the same CSV format as the CLI
The GUI uses one location-wide irradiance and temperature value for all panels. When importing a CSV whose rows use different climate values, it uses the first row's values and reports a warning.
CLI usage #
Run a simulation from an input CSV:
./builddir/src/panel-modeler input.csv output.csv
Print help or the version:
./builddir/src/panel-modeler --help
./builddir/src/panel-modeler --version
When Qt is available, look up climate data directly:
./builddir/src/panel-modeler --climate 33.44,-112.07
./builddir/src/panel-modeler --climate "Phoenix, AZ"
The lookup prints a ready-to-edit CSV line. Coordinates use latitude,longitude order. Addresses are resolved with OpenStreetMap Nominatim, then climate data is retrieved from NASA POWER.
Input CSV format #
The first line is the number of years to simulate. Each following non-empty line has five or six comma-separated values:
- Reference power per panel in watts
- Average irradiance in watts per square meter
- Average temperature in degrees Celsius
- Temperature derating coefficient of power, as a decimal fraction per degree Celsius
- Decay rate per year, as a decimal fraction
- Number of identical panels in the array (optional; defaults to
1)
Example: tests/ExamplePanelData.csv
25
400.0, 196.07, 13.5, -0.0035, 0.0045, 12
This describes an array of 12 identical 400 W panels. Existing five-value rows remain valid and represent a single panel.
The percentage-style values are entered as decimal fractions, not whole percentages:
-0.0043 means -0.43% per °C, and 0.0045 means 0.45% per year.
The parser accepts arbitrary decimal precision. The parser limits years to 100, irradiance
to 0–2000 W/m², temperature to -50–60 °C, temperature derating to -0.05–0.05, and decay
to 0–0.10. Values outside those ranges are clamped with warnings.
Output and equation #
Output contains one header row and one row for each year, starting at Year 0. Each panel column represents the total output for that array, calculated as per-panel output multiplied by its panel count. The historical formatting is intentionally stable so existing spreadsheets and expected output files remain compatible.
The estimate is:
P = P_ref * (I / 1000) * (1 + c_T * (T - 25)) * (1 - d)^years
where:
P_refis reference panel powerIis average irradiance in W/m²Tis average temperature in °Cc_Tis the temperature derating coefficient as a decimal fraction (for example,-0.0043=-0.43%/°C)dis the annual decay rate as a decimal fraction (for example,0.0045=0.45%/year)
This is an intentionally simplified model, not a bankable production forecast.
Network climate data #
The network feature uses:
- NASA POWER climatology API for
ALLSKY_SFC_SW_DWNandT2M. The API reports irradiance in kWh/m²/day; the application converts its annual value to average W/m². The climatology endpoint represents the 2001–2020 period in the current API response. - OpenStreetMap Nominatim for address-to-coordinate lookup.
Network requests require internet access. Nominatim has a usage policy and should not be treated as a bulk geocoding service. For repeated or production use, configure an appropriate geocoding provider or host your own service. The fetched values are editable because annual climatology is an approximation and may not match a project's preferred weather dataset.
Panel database #
The bundled database is data/panels.json. Values are nominal
examples and should be checked against current manufacturer datasheets before use.
The GUI can load a remote JSON database from a URL, making self-hosting straightforward:
cd data
python3 -m http.server 8000
Then enter:
http://127.0.0.1:8000/panels.json
A database document has this shape:
{
"version": 1,
"panels": [
{
"manufacturer": "Example Solar",
"model": "Example 400 W",
"referencePower": 400.0,
"tempDeratingCoeffPwr": -0.0035,
"decayRate": 0.005
}
]
}
For an installed application, the local database is searched in this order:
- The path in
PANEL_MODELER_PANEL_DB panels.jsonnext to the executable<prefix>/share/panel-modeler/panels.json
The GUI remembers the last remote database URL using QSettings.
Repository layout #
src/core/ STL-only simulation and CSV code
src/net/ Qt network services and panel database loading
src/cli/ CSV and climate lookup command-line entry point
src/gui/ Qt Widgets application and custom chart
data/ bundled panel database
tests/ regression input, expected output, and test runner
The core library has no Qt dependency, so it can still be built and tested with
-Dqt=disabled. The old raw arrays and heap-allocated streams were replaced with
std::vector and RAII streams; CsvIO is now stateless and Simulation::run owns
the common result-generation path used by both frontends.
Tests #
Run the Meson regression test:
meson test -C builddir
It runs the CLI against tests/ExamplePanelData.csv and compares the output
byte-for-byte with tests/ExpectedOutputData.csv.
Zed and clangd #
Meson generates builddir/compile_commands.json. The project includes
.zed/settings.json, which tells Zed's clangd integration to
use builddir as the compilation-database directory. Run Meson setup once before
opening source files so the database exists:
meson setup builddir --native-file clang.ini
The repository also keeps an ignored root symlink named compile_commands.json for
other clangd integrations and tools. Recreate it if the symlink is removed:
ln -sf builddir/compile_commands.json compile_commands.json
The optional infrastructure repository contains a rootless Podman service at
spruce-infra/panel-modeler/ that serves a self-hosted database internally at
http://panel-modeler-panels/panels.json. The GUI defaults to the public endpoint
https://panels.willowidk.dev/panels.json, while the Panel Database dialog still allows
the URL to be changed.
Mirroring to GitHub #
Tangled is the source of truth for this repository. The Tangled pipeline at
.tangled/workflows/mirror.yml mirrors every branch
and tag push to GitHub.
Configure these repository secrets in Tangled:
GITHUB_TOKEN: a GitHub fine-grained personal access token with Contents: Read and write permission on the destination repositoryGITHUB_REPOSITORY: the GitHub destination inowner/repositoryform
The workflow uses git push --mirror, so the GitHub repository should be dedicated to
this mirror and should not receive independent changes. The destination must already
exist on GitHub.