man/man1/gendaymtx.1

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