# pssolar

Plot day-light terminators and other sunlight parameters

## Synopsis

gmt pssolar [ -B[p|s]parameters ] [ -C ] [ -G[fill] ] [ -I[lon/lat][+d date][+z TZ] ] [ -J parameters ] [ -K ] [ -M ] [ -N ] [ -O ] [-P ] [ -R region ] [ -T dcna[+d date][+z TZ]] [ -U[stamp] ] [ -V[level] ] [ -W pen ] [ -X[a|c|f|r][xshift] ] [ -Y[a|c|f|r][yshift] ] [ -bo binary ] [ -o flags ] [ -p flags ] [ -t transp ] [ --PAR=value ]

## Description

solar calculates closed polygons for the day-night terminator and the civil, nautical and astronomical twilights and either writes them to standard output or uses them for clipping or filling on maps.

## Required Arguments

None.

## Optional Arguments

-B[p|s]parameters

  Set map boundary frame and axes attributes. (See full description) (See cookbook information).

-C

  Formats the report selected by -I using tab-separated fields on a single line. The output is Sun Lon Lat Azimuth Elevation in degrees, Sunrise Sunset Noon in decimal days, day length in minutes, SolarElevationCorrected corrected for the effect of refraction index and Equation of time in minutes. Note that if no position is provided in -I lon/lat the data after Elevation refers to the point (0,0).

-G[fill] (more …)

  Select color or pattern for filling of terminators, or give no argument for clipping [Default is no fill or clipping]. Deactivate clipping by appending the output of gmt clip -C.

-I[lon/lat][+d date][+z TZ]

  Print current sun position as well as Azimuth and Elevation. Append lon/lat to print also the times of Sunrise, Sunset, Noon and length of the day.

  The default time is now. To select another time, use these two modifiers:

  - +d - Print date in ISO 8601 format, e.g, +d 2000-04-25T04:52, to compute sun parameters for this date and time [Default is now].

  - +z - If necessary, append the time zone TZ. The time zone is given as an offset from UTC. Negative offsets look like −03:00 or −03. Positive offsets look like 02:00 or 02.

-J parameters

  Specify the projection. (See full description) (See cookbook summary) (See projections table).

-M

  Write terminator(s) as a multisegment ASCII (or binary, see -b o) polygons to standard output. No plotting occurs.

-N

  Invert the sense of what is inside and outside the terminator. Only used with clipping (-G) and cannot be used together with -B.

-R xmin/xmax/ymin/ymax[+r][+u unit]

  Specify the region of interest. (See full description) (See cookbook information).

-Tdcna[+d date][+z TZ]

  Plot (or dump; see -M) one or more terminators by appending any of these directives:

  - d - Select the day/night terminator.

  - c - Select civil twilight.

  - n - Select nautical twilight;

  - a - Select astronomical twilight.

  The default time is now. To select another time, use these two modifiers:

  - +d - Append date in ISO format, e.g, +d 2000-04-25T12:15:00 to know where the day-night was at that date [Default is now]

  - +z - If necessary, append the time zone TZ. The time zone is given as an offset from UTC. Negative offsets look like −03:00 or −03. Positive offsets look like 02:00 or 02.

  Refer to https://en.wikipedia.org/wiki/Twilight for definitions of different twilights.

-U[label|+c][+j justify][+o dx[/dy]][+t text]

  Draw GMT time stamp logo on plot. (See full description) (See cookbook information).

-V[level]

  Select verbosity level [w]. (See full description) (See cookbook information).

-W[pen] (more …)

  Set pen attributes for lines or the outline of symbols [Defaults: width = 0.25p, color = black, style = solid].

-X[a|c|f|r][xshift]

  Shift plot origin. (See full description) (See cookbook information).

-Y[a|c|f|r][yshift]

  Shift plot origin. (See full description) (See cookbook information).

-bo record[+b|l] (more …)

  Select native binary format for table output.

-o cols[+l][+d divisor][+s scale|d|k][+o offset][,…][,t[word]] (more …)

  Select output columns and transformations (0 is first column, t is trailing text, append word to write one word only).

-p[x|y|z]azim[/elev[/zlevel]][+w lon0/lat0[/z0]][+v x0/y0] (more …)

  Select perspective view.

-t transp[/transp2] (more …)

  Set transparency level(s) in percent.

-^ or just -

  Print a short message about the syntax of the command, then exit (Note: on Windows just use -).

-+ or just +

  Print an extensive usage (help) message, including the explanation of any module-specific option (but not the GMT common options), then exit.

-? or no arguments

  Print a complete usage (help) message, including the explanation of all options, then exit.

--PAR=value

  Temporarily override a GMT default setting; repeatable. See gmt.conf for parameters.

## Classic Mode Arguments

These options are used to manipulate the building of layered GMT PostScript plots in classic mode. They are not available when using GMT modern mode.

-K (more …)

  Do not finalize the PostScript plot.

-O (more …)

  Append to existing PostScript plot.

-P (more …)

  Select “Portrait” plot orientation.

## Examples

Note: Below are some examples of valid syntax for this module. The examples that use remote files (file names starting with `@`) can be cut and pasted into your terminal for testing. Other commands requiring input files are just dummy examples of the types of uses that are common but cannot be run verbatim as written.

Print current Sun position and Sunrise, Sunset times at given date, time and time zone:

    gmt pssolar -I-7.93/37.079+d2016-02-04T10:01:00+z02:00

Plot the day-night and civil twilight:

    gmt pscoast -Rd -W0.1p -JQ0/14c -Ba -BWSen -Dl -A1000 -P -K > terminator.ps
    gmt pssolar -R -J -W1p -Tdc -O >> terminator.ps

Set up a clip path overlay based on the day/night terminator:

    gmt pssolar -R -J -G -Tc -O -K >> someplot.ps

## References

Code from the Excel Spreadsheets in http://www.esrl.noaa.gov/gmd/grad/solcalc/calcdetails.html

## Notes

Taken from the NOAA site Data for Litigation note.

> The NOAA Solar Calculator is for research and recreational use only. NOAA cannot certify or authenticate sunrise, sunset or solar position data. The U.S. Government does not collect observations of astronomical data, and due to atmospheric conditions our calculated results may vary significantly from actual observed values.

> For further information, please see the U.S. Naval Observatory’s page Astronomical Data Used for Litigation

## See Also

gmt, psclip, pscoast, psxy