man/man1/dctimestep.1

.\" RCSid $Id: dctimestep.1,v 1.17 2022/03/11 02:27:02 greg Exp $"
.TH DCTIMESTEP 1 12/09/09 RADIANCE
.SH NAME
dctimestep - compute annual simulation time-step(s) via matrix multiplication
.SH SYNOPSIS
.B dctimestep
[
.B "\-n nsteps"
][
.B "\-h"
][
.B "\-o ospec"
][
.B "\-x xres"
][
.B "\-y yres"
][
.B "\-i{f|d}
][
.B "\-o{f|d|c}
]
.B DCspec
[
.B skyf
]
.br
.B dctimestep
[
.B "\-n nsteps"
][
.B "\-h"
][
.B "\-o ospec"
][
.B "\-i{f|d}
][
.B "\-o{f|d}
]
.B Vspec
.B Tbsdf
.B Dmat.dat
[
.B skyf
]
.SH DESCRIPTION
.I Dctimestep
has two invocation forms.
In the first form,
.I dctimestep
is given a daylight coefficient specification and an optional sky
vector or matrix, which may be read from the standard input if unspecified.
The daylight coefficients are multiplied against these sky values
and the results are written to the standard output.
This may be a list of color values or a combined Radiance picture,
as explained below.
.PP
In the second form,
.I dctimestep
takes four input files, forming a matrix expression.
The first argument is the View matrix that specifies how window output
directions are related to some set of measured values, such as an array of
illuminance points or pictures.
This matrix is usually computed by
.I rfluxmtx(1)
or
.I rcontrib(1)
for a particular set of windows or skylight openings.
The second argument is the window transmission matrix, or BSDF, given as
a matrix or a standard XML description.
The third argument is the Daylight matrix file that defines how sky patches
relate to input directions on the same opening.
This is usually computed using
.I rfluxmtx
with separate runs for each window or skylight orientation.
The last file is the sky contribution vector or matrix,
typically computed by
.I genskyvec(1)
or
.I gendaymtx(1),
and may be passed on the standard input.
.PP
If the input sky data lacks a header, the
.I \-n
option may be used to indicate the number of time steps, which
will be 1 for a sky vector.
The sky input file must otherwise contain the number of
columns (time steps) specified in each sky patch row,
whether it is read from the standard input or from a file.
Input starts from the first patch at the first time step, then the
first patch at the second time step, and so on.
Note that all matrix elements are RGB triplets, so the actual size
of the sky vector or matrix is three times the number of steps times
the number of sky patches.
The
.I \-if
or
.I \-id
option may be used to specify that sky data is in float or double
format, respectively, which is more efficient for large matrices.
These options are unnecessary when the sky input includes a header.
.PP
Any of the matrix or vector files may be read from a command
instead of a file by
using quotes and a beginning exclamation point ('!').
.PP
The standard output of
.I dctimestep
is either a color vector with as many RGB triplets
as there are rows in the View matrix, or a combined
.I Radiance
picture.
Which output is produced depends on the first argument.
A regular file name will be loaded and interpreted as a matrix to
generate a color results vector.
A file specification containing a '%d' format string will be
interpreted as a list of
.I Radiance
component pictures, which will be summed according to the computed
vector.
.PP
The
.I \-o
option may be used to specify a file or a set of output files
to use rather than the standard output.
If the given specification contains a '%d' format string, this
will be replaced by the time step index, starting from 0.
In this way, multiple output pictures may be produced,
or separate result vectors (one per time step).
If input is a matrix rather than a set of pictures, the
.I \-x
and/or
.I \-y
options may be necessary to set the output picture size.
If only one dimension is specified, the other is computed based
on the number of rows in the result vectors.
.PP
A header will normally be produced on the output, unless the
.I \-h
option is specified.
The
.I \-of,
.I \-od,
or
.I \-oc
option may be used to specify IEEE float, double, or RGBE (picture) output
data, respectively.
.SH EXAMPLES
To compute workplane illuminances at 3:30pm on Feb 10th:
.IP "" .2i
gensky 2 10 15:30 | genskyvec | dctimestep workplaneDC.dmx > Ill_02-10-1530.dat
.PP
To compute a picture at 10am on the equinox from a set of component pictures:
.IP "" .2i
gensky 3 21 10 | genskyvec | dctimestep dcomp%03d.hdr > view_03-21-10.hdr
.PP
To compute a set of illuminance contributions for Window 1 on
the Winter solstice at 2pm:
.IP "" .2i
gensky 12 21 14 | genskyvec | dctimestep IllPts.vmx Blinds20.xml Window1.dmx > Ill_12-21-14.dat
.PP
To compute Window2's contribution to an interior view at 12 noon on the Summer solstice:
.IP "" .2i
gensky 6 21 12 | genskyvec | dctimestep view%03d.hdr Blinds30.xml
Window2.dmx > view_6-21-12.hdr
.PP
To generate an hourly matrix of sensor value contributions from Skylight3
using a 3-phase calculation, where output columns are time steps:
.IP "" .2i
gendaymtx -of Tampa.wea | dctimestep WPpts.vmx
shade3.xml Skylight3.dmx > wp_win3.dat
.PP
Generate a series of pictures corresponding to timesteps
in an annual simulation:
.IP "" .2i
gendaymtx NYCity.wea | dctimestep -o tstep%04d.hdr dcomp%03d.hdr
.PP
To multiply an irradiance view matrix through a pair of XML window layers using
a given exterior daylight matrix and sky vector:
.IP "" .2i
dctimestep Illum.vmx "!rmtxop -ff Blinds1.xml Windo1.xml" Exter.dmx Jan20.sky
.PP
To multiply two matrices into a IEEE-float result with header:
.IP "" .2i
dctimestep -of Inp1.fmx Inp2.fmx > Inp1xInp2.fmx
.SH NOTES
.I Dctimestep
optimizes its matrix concatenation by checking for all-zero rows
or columns, thus avoiding unnecessary vector multiplications.
This can improve performance when a daylight matrix contains
zero-filled column vectors corresponding to hours of darkness.
.PP
It rarely makes sense to specify the
.I \-od
output option with
.I dctimestep,
since matrix operations are carried out using 32-bit "float" values.
This take less memory, but can also be less accurate than an
equivalent invocation of
.I rmtxop(1),
which performs all operations on 64-bit "double" values.
.SH AUTHOR
Greg Ward
.SH "SEE ALSO"
gendaymtx(1), genskyvec(1), getinfo(1),
mkillum(1), rcollate(1), rcontrib(1), rcrop(1),
rfluxmtx(1), rmtxop(1), rtrace(1), vwrays(1)
Revision:	1.18
Committed:	Wed Mar 23 01:52:51 2022 UTC (3 years, 1 month ago) by greg
Branch:	MAIN
CVS Tags:	rad5R4
Changes since 1.17:	+24 -8 lines
Log Message:	docs(dctimestep): Changed some wording and added a NOTES section
#	Content
1	.\" RCSid $Id: dctimestep.1,v 1.17 2022/03/11 02:27:02 greg Exp $"
2	.TH DCTIMESTEP 1 12/09/09 RADIANCE
3	.SH NAME
4	dctimestep - compute annual simulation time-step(s) via matrix multiplication
5	.SH SYNOPSIS
6	.B dctimestep
7	[
8	.B "\-n nsteps"
9	][
10	.B "\-h"
11	][
12	.B "\-o ospec"
13	][
14	.B "\-x xres"
15	][
16	.B "\-y yres"
17	][
18	.B "\-i{f\|d}
19	][
20	.B "\-o{f\|d\|c}
21	]
22	.B DCspec
23	[
24	.B skyf
25	]
26	.br
27	.B dctimestep
28	[
29	.B "\-n nsteps"
30	][
31	.B "\-h"
32	][
33	.B "\-o ospec"
34	][
35	.B "\-i{f\|d}
36	][
37	.B "\-o{f\|d}
38	]
39	.B Vspec
40	.B Tbsdf
41	.B Dmat.dat
42	[
43	.B skyf
44	]
45	.SH DESCRIPTION
46	.I Dctimestep
47	has two invocation forms.
48	In the first form,
49	.I dctimestep
50	is given a daylight coefficient specification and an optional sky
51	vector or matrix, which may be read from the standard input if unspecified.
52	The daylight coefficients are multiplied against these sky values
53	and the results are written to the standard output.
54	This may be a list of color values or a combined Radiance picture,
55	as explained below.
56	.PP
57	In the second form,
58	.I dctimestep
59	takes four input files, forming a matrix expression.
60	The first argument is the View matrix that specifies how window output
61	directions are related to some set of measured values, such as an array of
62	illuminance points or pictures.
63	This matrix is usually computed by
64	.I rfluxmtx(1)
65	or
66	.I rcontrib(1)
67	for a particular set of windows or skylight openings.
68	The second argument is the window transmission matrix, or BSDF, given as
69	a matrix or a standard XML description.
70	The third argument is the Daylight matrix file that defines how sky patches
71	relate to input directions on the same opening.
72	This is usually computed using
73	.I rfluxmtx
74	with separate runs for each window or skylight orientation.
75	The last file is the sky contribution vector or matrix,
76	typically computed by
77	.I genskyvec(1)
78	or
79	.I gendaymtx(1),
80	and may be passed on the standard input.
81	.PP
82	If the input sky data lacks a header, the
83	.I \-n
84	option may be used to indicate the number of time steps, which
85	will be 1 for a sky vector.
86	The sky input file must otherwise contain the number of
87	columns (time steps) specified in each sky patch row,
88	whether it is read from the standard input or from a file.
89	Input starts from the first patch at the first time step, then the
90	first patch at the second time step, and so on.
91	Note that all matrix elements are RGB triplets, so the actual size
92	of the sky vector or matrix is three times the number of steps times
93	the number of sky patches.
94	The
95	.I \-if
96	or
97	.I \-id
98	option may be used to specify that sky data is in float or double
99	format, respectively, which is more efficient for large matrices.
100	These options are unnecessary when the sky input includes a header.
101	.PP
102	Any of the matrix or vector files may be read from a command
103	instead of a file by
104	using quotes and a beginning exclamation point ('!').
105	.PP
106	The standard output of
107	.I dctimestep
108	is either a color vector with as many RGB triplets
109	as there are rows in the View matrix, or a combined
110	.I Radiance
111	picture.
112	Which output is produced depends on the first argument.
113	A regular file name will be loaded and interpreted as a matrix to
114	generate a color results vector.
115	A file specification containing a '%d' format string will be
116	interpreted as a list of
117	.I Radiance
118	component pictures, which will be summed according to the computed
119	vector.
120	.PP
121	The
122	.I \-o
123	option may be used to specify a file or a set of output files
124	to use rather than the standard output.
125	If the given specification contains a '%d' format string, this
126	will be replaced by the time step index, starting from 0.
127	In this way, multiple output pictures may be produced,
128	or separate result vectors (one per time step).
129	If input is a matrix rather than a set of pictures, the
130	.I \-x
131	and/or
132	.I \-y
133	options may be necessary to set the output picture size.
134	If only one dimension is specified, the other is computed based
135	on the number of rows in the result vectors.
136	.PP
137	A header will normally be produced on the output, unless the
138	.I \-h
139	option is specified.
140	The
141	.I \-of,
142	.I \-od,
143	or
144	.I \-oc
145	option may be used to specify IEEE float, double, or RGBE (picture) output
146	data, respectively.
147	.SH EXAMPLES
148	To compute workplane illuminances at 3:30pm on Feb 10th:
149	.IP "" .2i
150	gensky 2 10 15:30 \| genskyvec \| dctimestep workplaneDC.dmx > Ill_02-10-1530.dat
151	.PP
152	To compute a picture at 10am on the equinox from a set of component pictures:
153	.IP "" .2i
154	gensky 3 21 10 \| genskyvec \| dctimestep dcomp%03d.hdr > view_03-21-10.hdr
155	.PP
156	To compute a set of illuminance contributions for Window 1 on
157	the Winter solstice at 2pm:
158	.IP "" .2i
159	gensky 12 21 14 \| genskyvec \| dctimestep IllPts.vmx Blinds20.xml Window1.dmx > Ill_12-21-14.dat
160	.PP
161	To compute Window2's contribution to an interior view at 12 noon on the Summer solstice:
162	.IP "" .2i
163	gensky 6 21 12 \| genskyvec \| dctimestep view%03d.hdr Blinds30.xml
164	Window2.dmx > view_6-21-12.hdr
165	.PP
166	To generate an hourly matrix of sensor value contributions from Skylight3
167	using a 3-phase calculation, where output columns are time steps:
168	.IP "" .2i
169	gendaymtx -of Tampa.wea \| dctimestep WPpts.vmx
170	shade3.xml Skylight3.dmx > wp_win3.dat
171	.PP
172	Generate a series of pictures corresponding to timesteps
173	in an annual simulation:
174	.IP "" .2i
175	gendaymtx NYCity.wea \| dctimestep -o tstep%04d.hdr dcomp%03d.hdr
176	.PP
177	To multiply an irradiance view matrix through a pair of XML window layers using
178	a given exterior daylight matrix and sky vector:
179	.IP "" .2i
180	dctimestep Illum.vmx "!rmtxop -ff Blinds1.xml Windo1.xml" Exter.dmx Jan20.sky
181	.PP
182	To multiply two matrices into a IEEE-float result with header:
183	.IP "" .2i
184	dctimestep -of Inp1.fmx Inp2.fmx > Inp1xInp2.fmx
185	.SH NOTES
186	.I Dctimestep
187	optimizes its matrix concatenation by checking for all-zero rows
188	or columns, thus avoiding unnecessary vector multiplications.
189	This can improve performance when a daylight matrix contains
190	zero-filled column vectors corresponding to hours of darkness.
191	.PP
192	It rarely makes sense to specify the
193	.I \-od
194	output option with
195	.I dctimestep,
196	since matrix operations are carried out using 32-bit "float" values.
197	This take less memory, but can also be less accurate than an
198	equivalent invocation of
199	.I rmtxop(1),
200	which performs all operations on 64-bit "double" values.
201	.SH AUTHOR
202	Greg Ward
203	.SH "SEE ALSO"
204	gendaymtx(1), genskyvec(1), getinfo(1),
205	mkillum(1), rcollate(1), rcontrib(1), rcrop(1),
206	rfluxmtx(1), rmtxop(1), rtrace(1), vwrays(1)