Basics
Overview¶
This section introduces the basic structure of the command line interface, various commands, required arguments and optional parameters as well as some insight into generating arbitrary series of Timestamps.
-
Generic structure
-
Positional parameters
-
No prefixing
-
Strict order
-
<1>,<2>and<3>are required
for -
[4]and[5]are optional
for [Orientation] and [Tilt]
-
-
Working examples
Example
- Examples that should just work
-
Examples that fail
Danger
- Examples that fail so we know it is no-one's fault!
Generic Structure¶
The fundamental structure of the command line interface is a command and a sub-command following the name of the program pvgis-prototype and a series of required positional, optional positional and named optional input parameters. Like so :
Example
where :
poweris the commandbroadbanda sub-command8 45are the Longitude and Latitude214is the Elevation170 44are the Orientation and Tilt angles
Several commands feature chained sub-sub-commands. The structure remains the same and a sub-command sub-sub-command only add up to the command which indeed follows the generic program name pvgis-prototype like
pvgis-prototype \
<command> \
<sub-command> \
<sub-sub-command> \
<1> <2> <3> [4] [5] \
<--option-a 'a'> \
<--option-b 'b'> \
..
Example
To calculate the global horizontal irradiance at our example location and at '2010-01-27 12:00:00' we can do
For clarity, let's look at the command's parts written out one part per line
where :
irradianceis the commandglobala sub-commandhorizontala sub-sub-command8 45 214the Longitude, Latitude and Elevation- '2010-01-27 12:00:00' the requested timestamp
Example
We can calculate the global inclined irradiance at our example location and at '2010-01-27 12:00:00' via
For clarity, let's look at the command's parts written out one part per line
where :
irradianceis the commandglobala sub-commandinclineda sub-sub-command8 45 214 170 44the Longitude, Latitude, Elevation, surface Orientation and surface Tilt- '2010-01-27 12:00:00' the requested timestamp
Positional parameters¶
- The numbers
<1>,<2>and<3>enumerate the required positional parameters. - The numbers
[4]and[5]enumerate two optional yet positional parameters. - Positional parameters need no prefixing. However, they are required to be given strictly in the pre-specified order.
Optional parameters¶
Optional parameters need
-
to be named, for example
--verboseor its equivalent simpler form-v. -
not to be given in a specific order, i.e. asking for
-v --uniplotis the same as--uniplot -v.
Location¶
With a few exceptions, the performance, power, irradiance and position commands, require at the very least the three basic input parameters that describe the location of a solar surface. A more descriptive representation of the basic command structure is :
Orientation and Tilt¶
What follows after the location parameters is the pair of orientation and tilt angles of the solar surface in question.
If not provided, the default pre-set values are orientation = 180 and tilt = 45 degrees.
Time¶
Of course, time is the first variable that determines the position of the sun in the sky and therefore impacts each and every calculation that depends on it. Nonetheless, in PVGIS, it comes as the last required positional parameter! The importance of time is such that we have a dedicated section called Timestamps !
The default timestamp is your computer's current time and local zone!
However, for the sake of ease of use and practice, if not given, the timestamp/s is set form your system's current local time and zone.
Attention
If a specific timestamp or series of timestamps are given, then all required input arguments are expected to be given. Missing one of the positional required parameters will cause the program to exit with an error message asking for the next missing input parameter. See following examples.
Examples that work¶
Without a timestamp¶
Example that works with all positional parameters yet without a timestamp :
As mentioned above, this command will run with your computer's current local time and zone. We can see for example which timestamp the command ran for by adding some verbosity :
Global Inclined Irradiance in-plane irradiance
series W/m²
Time Global ⤋ ∡ Direct ⇣ ∡ ☉
─────────────────────────────────────────────────
2025-12-01 22:11:41 0.0 0.0
⅀ / μ 0.0 0.0
╭────────────────────────────────────────────────────────────────────────────────────╮ ╭───────────────────────────────────────────────╮
│ Location Longitude ϑ, Latitude ϕ = 0.14, 0.785, Elevation: 214.0 m │ │ ∡ Inclined ↻ Orientation μ Mean │
│ Position Surface Orientation ↻: 2.967, Surface Tilt ⦥: 0.768 Angular units None │ │ ⇣ Direct ⦥ Tilt │
│ Definitions Incidence angle: Sun-Vector-to-Surface-Plane, │ │ ⏲ Timing ⭸ Incidence │
│ Algorithms Timing : NOAA, Positioning : NOAA, Incidence : Iqbal │ │ ⯐ Positioning ⅀ N-ary Summation │
╰──────────────────────────────────────────────────────────────────────── Reference ─╯ ╰────────────────────────────────────── Legend ─╯
Where did this timestamp came from ?
The timestamp in the above command is the one of this very example's execution time which ran at build time of the interactive documentation you are reading.
Single timestamp¶
Example that works with all positional parameters including a timestamp:
Arbitrary number of single timestamps¶
Example that works with all positional parameters including multiple timestamps:
pvgis-prototype irradiance global inclined \
8 45 214 170 44 \
'2010-01-27 12:00:00, 2010-01-27 13:30:00, 2010-01-27 17:45:00'
The same as above, with additional verbosity :
pvgis-prototype irradiance global inclined 8 45 214 170 44 '2010-01-27 12:00:00, 2010-01-27 13:30:00, 2010-01-27 17:45:00' -v
Global Inclined Irradiance in-plane irradiance series W/m²
Time Global ⤋ ∡ Inclined Irradiance Direct ⇣ ∡ ☉ Sky-Diffuse 🗤 ∡ ☉ Ground-Diffuse ⭞ ∡ ☉
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────
2010-01-27 12:00:00 983.77 989.457 880.822 95.269 13.366
2010-01-27 13:30:00 792.855 800.395 704.774 84.837 10.784
2010-01-27 17:45:00 0.0 0.0 0.0 0.0 0.0
⅀ / μ 1776.625 1585.596 180.106 24.149
╭────────────────────────────────────────────────────────────────────────────────────╮ ╭───────────────────────────────────────────────────╮
│ Location Longitude ϑ, Latitude ϕ = 0.14, 0.785, Elevation: 214.0 m │ │ - Loss ⭞ Reflected ⦥ Tilt │
│ Position Surface Orientation ↻: 2.967, Surface Tilt ⦥: 0.768 Angular units None │ │ ∡ Inclined ⏲ Timing ⭸ Incidence │
│ Definitions Incidence angle: Sun-Vector-to-Surface-Plane, │ │ ⇣ Direct ⯐ Positioning ⅀ N-ary Summation │
│ Algorithms Timing : NOAA, Positioning : NOAA, Incidence : Iqbal │ │ 🗤 Diffuse ↻ Orientation μ Mean │
╰──────────────────────────────────────────────────────────────────────── Reference ─╯ ╰────────────────────────────────────────── Legend ─╯
Mixing optional parameters¶
pvgis-prototype irradiance global inclined \
8 45 214 170 44 \
'2010-01-27 12:00:00, 2010-01-27 13:30:00, 2010-01-27 17:45:00' \
-v \
--quiet
is the same as
pvgis-prototype irradiance global inclined \
8 45 214 170 44 \
'2010-01-27 12:00:00, 2010-01-27 13:30:00, 2010-01-27 17:45:00' \
--quiet \
--verbose
One more example mixing the order of options
pvgis-prototype irradiance global inclined \
8 45 214 170 44 \
'2010-01-27 12:00:00, 2010-01-27 13:30:00' \
-v \
--quiet \
-vv
--quiet silences the output
All of the above commands will not return anything since this is what the --quiet flag (or -q for the matter) is meant to do!
Examples that fail !¶
It is useful to get a sense of things that don't work too. Following are some examples that fail and ideally should return meaninfgul error messages.
Example that fails
Usage: pvgis-prototype irradiance global inclined [OPTIONS] LONGITUDE LATITUDE
ELEVATION
[SURFACE_ORIENTATION]
[SURFACE_TILT] [TIMESTAMPS]
Try 'pvgis-prototype irradiance global inclined --help' for help.
╭─ Error ───────────────────────────────────────────────────────────────────────────────╮
│ Invalid value for '[SURFACE_TILT]': '2010-01-27 12:00:00' is not a valid float range. │
╰───────────────────────────────────────────────────────────────────────────────────────╯
In the above example, the surface tilt angle is missing, followed by a user-requested timestamp. Due to the nature of the command line positional arguments, it is expected to follow strictly their order.
Another failing example
Usage: pvgis-prototype irradiance global inclined [OPTIONS] LONGITUDE LATITUDE
ELEVATION
[SURFACE_ORIENTATION]
[SURFACE_TILT] [TIMESTAMPS]
Try 'pvgis-prototype irradiance global inclined --help' for help.
╭─ Error ───────────────────────────────────────────────────────────────────────────────╮
│ Invalid value for '[SURFACE_TILT]': '2010-01-27 12:00:00' is not a valid float range. │
╰───────────────────────────────────────────────────────────────────────────────────────╯
In the above example, the surface orientation angle is missing, followed by a user-requested timestamp.
One more failing example
Usage: pvgis-prototype irradiance global inclined [OPTIONS] LONGITUDE LATITUDE
ELEVATION
[SURFACE_ORIENTATION]
[SURFACE_TILT] [TIMESTAMPS]
Try 'pvgis-prototype irradiance global inclined --help' for help.
╭─ Error ──────────────────────────────────────────────────────────────────────────────────────╮
│ Invalid value for '[SURFACE_ORIENTATION]': '2010-01-27 12:00:00' is not a valid float range. │
╰──────────────────────────────────────────────────────────────────────────────────────────────╯
In the last failing example, both the surface orientation and tilt angles are missing followed by a user-requested timestamp.