man/man1/gensdaymtx.1

.\" RCSid $Id: gensdaymtx.1,v 1.3 2025/03/27 01:26:55 greg Exp $
.TH GENSDAYMTX 1 01/19/13 RADIANCE
.SH NAME
gensdaymtx - generate an annual spectral sky matrix from a weather tape
.SH SYNOPSIS
.B gensdaymtx
[
.B "\-v"
][
.B "\-h"
][
.B "\-d|\-s"
][
.B "\-u"
]][
.B "\-r deg"
][
.B "\-m N"
][
.B "\-p Dir"
][
.B "\-n N"
][
.B "-o{f|d}"
]
[
.B "tape.wea"
or
.B "tape.epw"
]
.SH DESCRIPTION
.I Gensdaymtx
takes a weather tape as input and produces a matrix of spectral sky patch
values using the precomputed atmospheric scattering model.
Unlike the similarly-named
.I gendaymtx
tool, the Perez sky model is not used.
The weather tape is assumed to be in a special form of the .wea file, which contains 
a short header with the site parameters followed
by the month, day, standard time, direct normal and diffuse horizontal
illuminance values, total cloud cover, and broadband aerosol optical depth, one time step per line.
Alternatively, a standard EPW (EnergyPlus Weather) file may be provided.
Such file can be generated by 
.I epw2wea 
with the
.I \-a 
flag.
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
.I Gensdaymtx
uses the OPAC continental average aerosol profile for the Mie scattering calculation. 
For every distinct AOD value in the weather tape, a new set of the atmospheric parameters 
is computed and stored in the atmos_data directory in the current directory, which 
can be changed using the -p flag. This precomputation can be sped up using the
.I \-n NThreads
option. There is no speedup after NTHREADS=16.
.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 20 values, corresponding to
spectra from 380nm to 730nm at 20nm interval (watts/sr/meter^2).
Thus, an hourly weather tape for an entire year would
yield 8760x20 (175200) values per output line (row).
.PP
The
.I \-g
option may be used to specify a ground color.
The default value is
.I "\-g 0.2"
corresponding to a 20% gray.
.PP
If there is a sun in the description,
.I gensdaymtx
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.
.PP
By default,
.I gensdaymtx
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 \-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 annual spectral sky matrix without solar direct:
.IP "" .2i
epw2wea Detroit.epw Detroit.wea -a; 
gensdaymtx -m 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
gensdaymtx -m 4 -of VancouverBC.wea | dctimestep -if -n 8760 DCoef.mtx > res.dat
.SH AUTHORS
Taoning Wang
.SH "SEE ALSO"
dctimestep(1), epw2wea(1),
genBSDF(1), gendaylit(1), gendaymtx(1), gensky(1), genskyvec(1), genssky(1),
pvsum(1), rcollate(1), rcomb(1), rcontrib(1), rfluxmtx(1), rmtxop(1), xform(1)
Revision:	1.4
Committed:	Thu Apr 10 23:30:58 2025 UTC (3 weeks, 2 days ago) by greg
Branch:	MAIN
CVS Tags:	HEAD
Changes since 1.3:	+5 -2 lines
Log Message:	feat(gensdaymtx,genssky): TW fixed bug in genssky and added absolute calibration
#	User	Rev	Content
1	greg	1.4	.\" RCSid $Id: gensdaymtx.1,v 1.3 2025/03/27 01:26:55 greg Exp $
2	greg	1.1	.TH GENSDAYMTX 1 01/19/13 RADIANCE
3			.SH NAME
4			gensdaymtx - generate an annual spectral sky matrix from a weather tape
5			.SH SYNOPSIS
6			.B gensdaymtx
7			[
8			.B "\-v"
9			][
10			.B "\-h"
11			][
12			.B "\-d\|\-s"
13			][
14			.B "\-u"
15			]][
16			.B "\-r deg"
17			][
18			.B "\-m N"
19			][
20			.B "\-p Dir"
21			][
22			.B "\-n N"
23			][
24			.B "-o{f\|d}"
25			]
26			[
27			.B "tape.wea"
28	greg	1.4	or
29			.B "tape.epw"
30	greg	1.1	]
31			.SH DESCRIPTION
32			.I Gensdaymtx
33			takes a weather tape as input and produces a matrix of spectral sky patch
34			values using the precomputed atmospheric scattering model.
35	greg	1.2	Unlike the similarly-named
36			.I gendaymtx
37			tool, the Perez sky model is not used.
38	greg	1.1	The weather tape is assumed to be in a special form of the .wea file, which contains
39			a short header with the site parameters followed
40			by the month, day, standard time, direct normal and diffuse horizontal
41	greg	1.4	illuminance values, total cloud cover, and broadband aerosol optical depth, one time step per line.
42			Alternatively, a standard EPW (EnergyPlus Weather) file may be provided.
43	greg	1.1	Such file can be generated by
44			.I epw2wea
45	greg	1.2	with the
46	greg	1.1	.I \-a
47			flag.
48			Each time step line is used to compute a column in the output matrix,
49			where rows correspond to sky patch positions, starting with 0 for
50			the ground and continuing to 145 for the zenith using the default
51			.I "\-m 1"
52			parameter setting.
53			.PP
54			.I Gensdaymtx
55			uses the OPAC continental average aerosol profile for the Mie scattering calculation.
56			For every distinct AOD value in the weather tape, a new set of the atmospheric parameters
57			is computed and stored in the atmos_data directory in the current directory, which
58			can be changed using the -p flag. This precomputation can be sped up using the
59			.I \-n NThreads
60			option. There is no speedup after NTHREADS=16.
61			.PP
62			Increasing the
63			.I \-m
64			parameter yields a higher resolution
65			sky using the Reinhart patch subdivision.
66			For example, setting
67			.I "\-m 4"
68			yields a sky with 2305 patches plus one patch for the ground.
69			Each matrix entry is in fact 20 values, corresponding to
70			spectra from 380nm to 730nm at 20nm interval (watts/sr/meter^2).
71			Thus, an hourly weather tape for an entire year would
72			yield 8760x20 (175200) values per output line (row).
73			.PP
74			The
75			.I \-g
76			option may be used to specify a ground color.
77			The default value is
78			.I "\-g 0.2"
79			corresponding to a 20% gray.
80			.PP
81			If there is a sun in the description,
82			.I gensdaymtx
83			will include its contribution in the four nearest sky patches,
84			distributing energy according to centroid proximity.
85			The
86			.I \-d
87			option may be used to produce a sun-only matrix, with no sky contributions,
88			and the ground patch also set to zero.
89			Alternatively, the
90			.I \-s
91			option may be used to exclude any direct solar component from the output,
92			with the other sky and ground patches unaffected.
93			.PP
94			The
95			.I \-u
96			option ignores input times when the sun is below the horizon.
97			.PP
98			By default,
99			.I gensdaymtx
100			assumes the positive Y-axis points north such that the first sky patch
101			is in the Y-axis direction on the horizon, the second patch is just
102			west of that, and so on spiraling around to the final patch near the zenith.
103			The
104			.I \-r
105			(or
106			.I \-rz)
107			option rotates the sky the specified number of degrees counter-clockwise
108			about the zenith, i.e., west of north.
109			This is in keeping with the effect of passing the output of
110			.I gensky(1)
111			or
112			.I gendaylit(1)
113			through
114			.I xform(1)
115			using a similar transform.
116			.PP
117			The
118			.I \-of
119			or
120			.I \-od
121			option may be used to specify binary float or double output, respectively.
122			This is much faster to write and to read, and is therefore preferred on
123			systems that support it.
124			(MS Windows is not one of them.)\0
125			The
126			.I \-h
127			option prevents the output of the usual header information.
128			Finally, the
129			.I \-v
130			option will enable verbose reporting, which is mostly useful for
131			finding out how many time steps are actually in the weather tape.
132			.SH EXAMPLES
133			Produce an annual spectral sky matrix without solar direct:
134			.IP "" .2i
135			epw2wea Detroit.epw Detroit.wea -a;
136			gensdaymtx -m 1 -s Detroit.wea > Detroit.mtx
137			.PP
138			Produce an hourly, annual Reinhart sky matrix
139			with 2306 patches including solar contributions
140			and send float output to
141			.I dctimestep(1)
142			to compute a sensor value matrix:
143			.IP "" .2i
144			gensdaymtx -m 4 -of VancouverBC.wea \| dctimestep -if -n 8760 DCoef.mtx > res.dat
145			.SH AUTHORS
146	greg	1.2	Taoning Wang
147	greg	1.1	.SH "SEE ALSO"
148	greg	1.2	dctimestep(1), epw2wea(1),
149			genBSDF(1), gendaylit(1), gendaymtx(1), gensky(1), genskyvec(1), genssky(1),
150	greg	1.3	pvsum(1), rcollate(1), rcomb(1), rcontrib(1), rfluxmtx(1), rmtxop(1), xform(1)