man/man1/gendaymtx.1

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