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
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 like
pvgis \
<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 Inclined Irradiance
────────────────────────────────────────────────────
2026-08-07 16:03:19 251.586
⅀ / μ 251.586
╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ Angular units ㎭ radians │
│ Location Longitude, Latitude = 0.14, 0.785, Elevation: 214.0 m │
│ Position Surface Orientation: 2.967, Surface Tilt: 0.768 │
│ Definitions Zone : UTC, Incidence angle: Sun-Vector-to-Surface-Plane, Sun-Horizon Positions: Above, Low angle, │
│ Below, Shading states: Sunlit, Potentially-sunlit, In-shade, │
│ Algorithms Radiation model: Hofierka 2002, Timing : NOAA, Positioning : NOAA, Incidence : Iqbal, │
│ Constants Solar constant : 1360.8, Perigee : 0.048869, Eccentricity : 0.03344 │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────── Reference ─╯
╭──────────────────────╮
│ ∡ Tilt │
│ ⅀ N-ary Summation │
│ μ Mean │
│ │
│ │
│ │
╰───────────── 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 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 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
────────────────────────────────────────────────────
2010-01-27 12:00:00 983.77
2010-01-27 13:30:00 792.855
2010-01-27 17:45:00 0.0
⅀ / μ 1776.625
╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ Angular units ㎭ radians │
│ Location Longitude, Latitude = 0.14, 0.785, Elevation: 214.0 m │
│ Position Surface Orientation: 2.967, Surface Tilt: 0.768 │
│ Definitions Zone : UTC, Incidence angle: Sun-Vector-to-Surface-Plane, Sun-Horizon Positions: Above, Low angle, │
│ Below, Shading states: Sunlit, Potentially-sunlit, In-shade, │
│ Algorithms Radiation model: Hofierka 2002, Timing : NOAA, Positioning : NOAA, Incidence : Iqbal, │
│ Constants Solar constant : 1360.8, Perigee : 0.048869, Eccentricity : 0.03344 │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────── Reference ─╯
╭──────────────────────╮
│ ∡ Tilt │
│ ⅀ N-ary Summation │
│ μ Mean │
│ │
│ │
│ │
╰───────────── Legend ─╯
Mixing optional parameters¶
pvgis 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 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 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 irradiance global inclined [OPTIONS] {longitude} {latitude}
{elevation} [surface_orientation]
[surface_tilt] [timestamps]
Try 'pvgis 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 irradiance global inclined [OPTIONS] {longitude} {latitude}
{elevation} [surface_orientation]
[surface_tilt] [timestamps]
Try 'pvgis 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 irradiance global inclined [OPTIONS] {longitude} {latitude}
{elevation} [surface_orientation]
[surface_tilt] [timestamps]
Try 'pvgis 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.