man/man1/gendaymtx.1

.\" RCSid $Id: gendaymtx.1,v 1.9 2019/05/28 15:19:17 greg Exp $
.TH GENDAYMTX 1 01/19/13 RADIANCE
.SH NAME
gendaymtx - generate an annual Perez sky matrix from a weather tape
.SH SYNOPSIS
.B gendaymtx
[
.B "\-v"
][
.B "\-h"
][
.B "\-A"
][
.B "\-d|\-s"
][
.B "\-r deg"
][
.B "\-m N"
][
.B "\-g r g b"
][
.B "\-c r g b"
][
.B "-o{f|d}"
][
.B "-O{0|1}"
]
[
.B "tape.wea"
]
.SH DESCRIPTION
.I Gendaymtx
takes a weather tape as input and produces a matrix of sky patch
values using the Perez all-weather model.
The weather tape is assumed to be in the simple ASCII format understood
by DAYSIM, which contains a short header with the site parameters followed
by the month, day, standard time, direct normal and diffuse horizontal
irradiance values, one time step per line.
Each time step line is used to compute a column in the output matrix,
where rows correspond to sky patch positions, starting with 0 for
the ground and continuing to 145 for the zenith using the default
.I "\-m 1"
parameter setting.
.PP
Increasing the
.I \-m
parameter, typically by factors of two, yields a higher resolution
sky using the Reinhart patch subdivision.
For example, setting
.I "\-m 4"
yields a sky with 2305 patches plus one patch for the ground.
Each matrix entry is in fact three values, corresponding to
red green and blue radiance channels (watts/sr/meter^2).
Thus, an hourly weather tape for an entire year would
yield 8760x3 (26280) values per output line (row).
.PP
The
.I \-A
option tells
.I gendaymtx
to generate a single column corresponding to an average sky
computed over all the input time steps, rather than one
column per time step.
.PP
The
.I \-c
option may be used to specify a color for the sky.
The gray value should equal 1 for proper energy balance.
The default sky color is
.I "\-c 0.960 1.004 1.118".
Similarly, the
.I \-g
option may be used to specify a ground color.
The default value is
.I "\-g 0.2 0.2 0.2"
corresponding to a 20% gray.
.PP
The
.I \-d
option may be used to produce a sun-only matrix, with no sky contributions,
and the ground patch also set to zero.
Alternatively, the
.I \-s
option may be used to exclude any direct solar component from the output,
with the rest of the sky and ground patch unaffected.
If there is a sun in the description,
.I gendaymtx
will include its contribution in the four nearest sky patches,
distributing energy according to centroid proximity.
.PP
By default,
.I gendaymtx
assumes the positive Y-axis points north such that the first sky patch
is in the Y-axis direction on the horizon, the second patch is just
west of that, and so on spiraling around to the final patch near the zenith.
The
.I \-r
(or
.I \-rz)
option rotates the sky the specified number of degrees counter-clockwise
about the zenith, i.e., west of north.
This is in keeping with the effect of passing the output of
.I gensky(1)
or
.I gendaylit(1)
through
.I xform(1)
using a similar transform.
.PP
The
.I \-of
or
.I \-od
option may be used to specify binary float or double output, respectively.
This is much faster to write and to read, and is therefore preferred on
systems that support it.
(MS Windows is not one of them.)\0
The
.I \-O1
option specifies that output should be total solar radiance rather
than visible radiance.
The
.I \-h
option prevents the output of the usual header information.
Finally, the
.I \-v
option will enable verbose reporting, which is mostly useful for
finding out how many time steps are actually in the weather tape.
.SH EXAMPLES
Produce an uncolored Tregenza sky matrix without solar direct:
.IP "" .2i
gendaymtx -m 1 -c 1 1 1 -s Detroit.wea > Detroit.mtx
.PP
Produce an hourly, annual Reinhart sky matrix
with 2306 patches including solar contributions
and send float output to
.I dctimestep(1)
to compute a sensor value matrix:
.IP "" .2i
gendaymtx -m 4 -of VancouverBC.wea | dctimestep -if -n 8760 DCoef.mtx > res.dat
.SH AUTHORS
Ian Ashdown wrote most of the code,
based on Jean-Jacques Delaunay's original gendaylit(1) implementation.
Greg Ward wrote the final parameter parsing and weather tape conversion.
.SH "SEE ALSO"
dctimestep(1), genBSDF(1), gendaylit(1), gensky(1), genskyvec(1),
rcollate(1), rcontrib(1), xform(1)
Revision:	1.10
Committed:	Tue Jun 25 00:09:45 2019 UTC (6 years, 4 months ago) by greg
Branch:	MAIN
Changes since 1.9:	+11 -1 lines
Log Message:	Added gendaymtx -A option to efficiently compute average skies
#	User	Rev	Content
1	greg	1.10	.\" RCSid $Id: gendaymtx.1,v 1.9 2019/05/28 15:19:17 greg Exp $
2	greg	1.1	.TH GENDAYMTX 1 01/19/13 RADIANCE
3			.SH NAME
4			gendaymtx - generate an annual Perez sky matrix from a weather tape
5			.SH SYNOPSIS
6			.B gendaymtx
7			[
8			.B "\-v"
9			][
10	greg	1.6	.B "\-h"
11			][
12	greg	1.10	.B "\-A"
13			][
14	greg	1.1	.B "\-d\|\-s"
15			][
16	greg	1.2	.B "\-r deg"
17			][
18	greg	1.1	.B "\-m N"
19			][
20			.B "\-g r g b"
21			][
22			.B "\-c r g b"
23			][
24			.B "-o{f\|d}"
25	greg	1.4	][
26			.B "-O{0\|1}"
27	greg	1.1	]
28			[
29			.B "tape.wea"
30			]
31			.SH DESCRIPTION
32			.I Gendaymtx
33			takes a weather tape as input and produces a matrix of sky patch
34			values using the Perez all-weather model.
35			The weather tape is assumed to be in the simple ASCII format understood
36			by DAYSIM, which contains a short header with the site parameters followed
37			by the month, day, standard time, direct normal and diffuse horizontal
38			irradiance values, one time step per line.
39			Each time step line is used to compute a column in the output matrix,
40			where rows correspond to sky patch positions, starting with 0 for
41			the ground and continuing to 145 for the zenith using the default
42			.I "\-m 1"
43			parameter setting.
44			.PP
45			Increasing the
46			.I \-m
47			parameter, typically by factors of two, yields a higher resolution
48			sky using the Reinhart patch subdivision.
49			For example, setting
50			.I "\-m 4"
51			yields a sky with 2305 patches plus one patch for the ground.
52			Each matrix entry is in fact three values, corresponding to
53			red green and blue radiance channels (watts/sr/meter^2).
54			Thus, an hourly weather tape for an entire year would
55			yield 8760x3 (26280) values per output line (row).
56			.PP
57			The
58	greg	1.10	.I \-A
59			option tells
60			.I gendaymtx
61			to generate a single column corresponding to an average sky
62			computed over all the input time steps, rather than one
63			column per time step.
64			.PP
65			The
66	greg	1.1	.I \-c
67			option may be used to specify a color for the sky.
68	greg	1.7	The gray value should equal 1 for proper energy balance.
69	greg	1.1	The default sky color is
70			.I "\-c 0.960 1.004 1.118".
71			Similarly, the
72			.I \-g
73			option may be used to specify a ground color.
74			The default value is
75			.I "\-g 0.2 0.2 0.2"
76			corresponding to a 20% gray.
77			.PP
78			The
79			.I \-d
80	greg	1.9	option may be used to produce a sun-only matrix, with no sky contributions,
81			and the ground patch also set to zero.
82	greg	1.1	Alternatively, the
83			.I \-s
84	greg	1.9	option may be used to exclude any direct solar component from the output,
85			with the rest of the sky and ground patch unaffected.
86	greg	1.8	If there is a sun in the description,
87			.I gendaymtx
88			will include its contribution in the four nearest sky patches,
89			distributing energy according to centroid proximity.
90	greg	1.1	.PP
91	greg	1.3	By default,
92			.I gendaymtx
93			assumes the positive Y-axis points north such that the first sky patch
94			is in the Y-axis direction on the horizon, the second patch is just
95			west of that, and so on spiraling around to the final patch near the zenith.
96	greg	1.1	The
97	greg	1.2	.I \-r
98			(or
99			.I \-rz)
100			option rotates the sky the specified number of degrees counter-clockwise
101	greg	1.3	about the zenith, i.e., west of north.
102	greg	1.2	This is in keeping with the effect of passing the output of
103			.I gensky(1)
104			or
105			.I gendaylit(1)
106			through
107			.I xform(1)
108			using a similar transform.
109			.PP
110			The
111	greg	1.1	.I \-of
112			or
113			.I \-od
114			option may be used to specify binary float or double output, respectively.
115			This is much faster to write and to read, and is therefore preferred on
116			systems that support it.
117			(MS Windows is not one of them.)\0
118	greg	1.4	The
119			.I \-O1
120			option specifies that output should be total solar radiance rather
121			than visible radiance.
122	greg	1.6	The
123			.I \-h
124			option prevents the output of the usual header information.
125	greg	1.1	Finally, the
126			.I \-v
127			option will enable verbose reporting, which is mostly useful for
128			finding out how many time steps are actually in the weather tape.
129			.SH EXAMPLES
130			Produce an uncolored Tregenza sky matrix without solar direct:
131			.IP "" .2i
132			gendaymtx -m 1 -c 1 1 1 -s Detroit.wea > Detroit.mtx
133			.PP
134			Produce an hourly, annual Reinhart sky matrix
135			with 2306 patches including solar contributions
136			and send float output to
137			.I dctimestep(1)
138			to compute a sensor value matrix:
139			.IP "" .2i
140			gendaymtx -m 4 -of VancouverBC.wea \| dctimestep -if -n 8760 DCoef.mtx > res.dat
141			.SH AUTHORS
142			Ian Ashdown wrote most of the code,
143			based on Jean-Jacques Delaunay's original gendaylit(1) implementation.
144			Greg Ward wrote the final parameter parsing and weather tape conversion.
145			.SH "SEE ALSO"
146	greg	1.5	dctimestep(1), genBSDF(1), gendaylit(1), gensky(1), genskyvec(1),
147			rcollate(1), rcontrib(1), xform(1)