man/man1/gendaymtx.1

.\" RCSid $Id: gendaymtx.1,v 1.12 2020/04/13 17:12:19 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|\-n"
][
.B "\-D sunfile"
[
.B "\-M sunmods"
]][
.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 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
The
.I \-u
option ignores input times when the sun is below the horizon.
This is a convenient way to average daylight hours only with the
.I \-A
option or to ensure that matrix entries correspond to solar positions
produced with the
.I \-D
option, described below.
.PP
The
.I \-n
option may be used if no matrix output is desired at all.
This may be used to merely check the input, or in combination with the
.I \-D
option, below.
.PP
The
.I \-D
option may be used to specify an output file to contain a list of
solar positions and intensities corresponding to time steps in the
weather tape where the sun has any portion above the horizion.
Sun radiance values may be zero if the direct amount is zero on the input.
Sun modifiers and names will be indexed by the minute, numbered from
midnight, January 1st.
If a hyphen ('-') is given as the argument to
.I \-D,
then the sun descriptions  will be directed to the standard output.
This implies the
.I \-n
option just described.
If the
.I \-M
option is given as well, it will be used to record the modifier
names used in the
.I \-D
output, for convenient input to
.I rcontrib(1)
and
.I rfluxmtx(1).
.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), rfluxmtx(1), xform(1)
Revision:	1.13
Committed:	Sat Aug 15 03:28:56 2020 UTC (4 years, 9 months ago) by greg
Branch:	MAIN
CVS Tags:	rad5R3
Changes since 1.12:	+14 -4 lines
Log Message:	feat(gendaymtx): added -u option for daylight hours only
#	User	Rev	Content
1	greg	1.13	.\" RCSid $Id: gendaymtx.1,v 1.12 2020/04/13 17:12:19 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.11	.B "\-d\|\-s\|\-n"
15			][
16			.B "\-D sunfile"
17	greg	1.13	[
18	greg	1.12	.B "\-M sunmods"
19	greg	1.13	]][
20	greg	1.2	.B "\-r deg"
21			][
22	greg	1.1	.B "\-m N"
23			][
24			.B "\-g r g b"
25			][
26			.B "\-c r g b"
27			][
28			.B "-o{f\|d}"
29	greg	1.4	][
30			.B "-O{0\|1}"
31	greg	1.1	]
32			[
33			.B "tape.wea"
34			]
35			.SH DESCRIPTION
36			.I Gendaymtx
37			takes a weather tape as input and produces a matrix of sky patch
38			values using the Perez all-weather model.
39			The weather tape is assumed to be in the simple ASCII format understood
40			by DAYSIM, which contains a short header with the site parameters followed
41			by the month, day, standard time, direct normal and diffuse horizontal
42			irradiance values, one time step per line.
43			Each time step line is used to compute a column in the output matrix,
44			where rows correspond to sky patch positions, starting with 0 for
45			the ground and continuing to 145 for the zenith using the default
46			.I "\-m 1"
47			parameter setting.
48			.PP
49			Increasing the
50			.I \-m
51	greg	1.11	parameter yields a higher resolution
52	greg	1.1	sky using the Reinhart patch subdivision.
53			For example, setting
54			.I "\-m 4"
55			yields a sky with 2305 patches plus one patch for the ground.
56			Each matrix entry is in fact three values, corresponding to
57			red green and blue radiance channels (watts/sr/meter^2).
58			Thus, an hourly weather tape for an entire year would
59			yield 8760x3 (26280) values per output line (row).
60			.PP
61			The
62	greg	1.10	.I \-A
63			option tells
64			.I gendaymtx
65			to generate a single column corresponding to an average sky
66			computed over all the input time steps, rather than one
67			column per time step.
68			.PP
69			The
70	greg	1.1	.I \-c
71			option may be used to specify a color for the sky.
72	greg	1.7	The gray value should equal 1 for proper energy balance.
73	greg	1.1	The default sky color is
74			.I "\-c 0.960 1.004 1.118".
75			Similarly, the
76			.I \-g
77			option may be used to specify a ground color.
78			The default value is
79			.I "\-g 0.2 0.2 0.2"
80			corresponding to a 20% gray.
81			.PP
82			The
83			.I \-d
84	greg	1.9	option may be used to produce a sun-only matrix, with no sky contributions,
85			and the ground patch also set to zero.
86	greg	1.1	Alternatively, the
87			.I \-s
88	greg	1.9	option may be used to exclude any direct solar component from the output,
89			with the rest of the sky and ground patch unaffected.
90	greg	1.8	If there is a sun in the description,
91			.I gendaymtx
92			will include its contribution in the four nearest sky patches,
93			distributing energy according to centroid proximity.
94	greg	1.1	.PP
95	greg	1.11	The
96	greg	1.13	.I \-u
97			option ignores input times when the sun is below the horizon.
98			This is a convenient way to average daylight hours only with the
99			.I \-A
100			option or to ensure that matrix entries correspond to solar positions
101			produced with the
102			.I \-D
103			option, described below.
104			.PP
105			The
106	greg	1.11	.I \-n
107	greg	1.13	option may be used if no matrix output is desired at all.
108	greg	1.11	This may be used to merely check the input, or in combination with the
109			.I \-D
110			option, below.
111			.PP
112			The
113			.I \-D
114			option may be used to specify an output file to contain a list of
115			solar positions and intensities corresponding to time steps in the
116	greg	1.12	weather tape where the sun has any portion above the horizion.
117			Sun radiance values may be zero if the direct amount is zero on the input.
118			Sun modifiers and names will be indexed by the minute, numbered from
119			midnight, January 1st.
120			If a hyphen ('-') is given as the argument to
121			.I \-D,
122			then the sun descriptions will be directed to the standard output.
123			This implies the
124			.I \-n
125			option just described.
126			If the
127			.I \-M
128			option is given as well, it will be used to record the modifier
129			names used in the
130			.I \-D
131			output, for convenient input to
132			.I rcontrib(1)
133			and
134			.I rfluxmtx(1).
135	greg	1.11	.PP
136	greg	1.3	By default,
137			.I gendaymtx
138			assumes the positive Y-axis points north such that the first sky patch
139			is in the Y-axis direction on the horizon, the second patch is just
140			west of that, and so on spiraling around to the final patch near the zenith.
141	greg	1.1	The
142	greg	1.2	.I \-r
143			(or
144			.I \-rz)
145			option rotates the sky the specified number of degrees counter-clockwise
146	greg	1.3	about the zenith, i.e., west of north.
147	greg	1.2	This is in keeping with the effect of passing the output of
148			.I gensky(1)
149			or
150			.I gendaylit(1)
151			through
152			.I xform(1)
153			using a similar transform.
154			.PP
155			The
156	greg	1.1	.I \-of
157			or
158			.I \-od
159			option may be used to specify binary float or double output, respectively.
160			This is much faster to write and to read, and is therefore preferred on
161			systems that support it.
162			(MS Windows is not one of them.)\0
163	greg	1.4	The
164			.I \-O1
165			option specifies that output should be total solar radiance rather
166			than visible radiance.
167	greg	1.6	The
168			.I \-h
169			option prevents the output of the usual header information.
170	greg	1.1	Finally, the
171			.I \-v
172			option will enable verbose reporting, which is mostly useful for
173			finding out how many time steps are actually in the weather tape.
174			.SH EXAMPLES
175			Produce an uncolored Tregenza sky matrix without solar direct:
176			.IP "" .2i
177			gendaymtx -m 1 -c 1 1 1 -s Detroit.wea > Detroit.mtx
178			.PP
179			Produce an hourly, annual Reinhart sky matrix
180			with 2306 patches including solar contributions
181			and send float output to
182			.I dctimestep(1)
183			to compute a sensor value matrix:
184			.IP "" .2i
185			gendaymtx -m 4 -of VancouverBC.wea \| dctimestep -if -n 8760 DCoef.mtx > res.dat
186			.SH AUTHORS
187			Ian Ashdown wrote most of the code,
188			based on Jean-Jacques Delaunay's original gendaylit(1) implementation.
189			Greg Ward wrote the final parameter parsing and weather tape conversion.
190			.SH "SEE ALSO"
191	greg	1.5	dctimestep(1), genBSDF(1), gendaylit(1), gensky(1), genskyvec(1),
192	greg	1.12	rcollate(1), rcontrib(1), rfluxmtx(1), xform(1)