File: gyoto.1

package info (click to toggle)
gyoto 1.3.1-1
  • links: PTS, VCS
  • area: main
  • in suites: buster
  • size: 8,588 kB
  • sloc: cpp: 33,490; sh: 18,775; xml: 2,633; python: 1,424; makefile: 681; ansic: 314
file content (384 lines) | stat: -rw-r--r-- 15,153 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
.\" Process this file with
.\" groff -man -Tascii foo.1
.\"
.TH GYOTO 1 "JANUARY 2019" Science "User Manuals"
.SH NAME
Gyoto \- the General relativitY Orbit Tracer of Observatoire de Paris
.SH SYNOPSIS
gyoto [\fB\-\-silent\fR|\fB\-\-quiet\fR|\fB\-\-verbose\fR[=\fIN\fR]|\fB\-\-debug\fR]
      [\fB\-\-no\-sigfpe\fR]
      [\fB\-\-help\fR[=\fIclass\fR]] [\fB\-\-version\fR] [\fB\-\-list\fR]
      [\fB\-\-ispec\fR=\fIi0\fR:\fIi1\fR:\fIdi\fR] [\fB\-\-jspec\fR=\fIj0\fR:\fIj1\fR:\fIdj\fR]
      ([\fB\-\-imin\fR=\fIi0\fR] [\fB\-\-imax\fR=\fIi1\fR] [\fB\-\-di\fR=\fIdi\fR])
      ([\fB\-\-jmin\fR=\fIj0\fR] [\fB\-\-jmax\fR=\fIj1\fR] [\fB\-\-dj\fR=\fIdj\fR])
      [\fB\-\-time\fR=\fItobs\fR] [\fB\-\-tmin\fR=\fItmin\fR]
      [\fB\-\-fov\fR=\fIangle\fR] [\fB\-\-resolution\fR=\fInpix\fR] [\fB\-\-distance\fR=\fIdist\fR]
      [\fB\-\-paln\fR=\fIOmega\fR] [\fB\-\-inclination\fR=\fIi\fR] [\fB\-\-argument\fR=\fItheta\fR]
      [\fB\-\-nthreads\fR=\fInth\fR] [\fB\-\-nprocesses\fR=\fInworkers\fR]
      [\fB\-\-plugins\fR=\fIpluglist\fR]
      [\fB\-\-impact-coords\fR[=\fIfname.fits\fR]]
      [\fB\-\-unit\fR[=\fIunit\fR]]
      [\fB\-\-parameter\fR=\fIPath::Name\fR[=\fIvalue\fR]]
      [\fB\-\-xmlwrite\fR=\fIoutput.xml\fR]
      [\fB\-\-\fR] \fIinput.xml \fIoutput.fits
.SH DESCRIPTION
Gyoto is a framework for computing geodesics in curved
space-times. The \fBgyoto\fR utility program uses this framework to
compute images of astronomical objects in the vicinity of compact
objects (e.g. black-holes). Such images are distorted by strong
gravitational lensing.

\fBgyoto\fR takes a scenery description in XML format
(\fIinput.xml\fR), computes this scenery using relativistic
ray-tracing, and saves the result in FITS format.

A companion program, \fBgyotoy\fR(1), can be used to interactively
visualize a single geodesic in any Gyoto metric (the trajectory of a
single photon or massive particle).

Ray-tracing can be very time consuming. It is possible to interrupt
the process at any time by hitting ^C, which will save the
already-computed part of the image before exiting the program. You can
then compute the rest of the image later using the \fB\-\-jmin\fR
option.

.SH OPTIONS
The \fBgyoto\fR program accepts many options. Most have a long name
(e.g. \fB\-\-parameter\fR) and a short name (e.g. \fB\-E\fR). When an
option takes an argument, this argument must follow immediately the
short option (e.g. \fB\-E\fIPath::Name\fR) and be separated from the
long option by exactly the character "="
(e.g. \fB\-\-parameter\fR=\fIPath::Name\fR). Long options can be
abbreviated as long as the abbreviation is unambiguous
(e.g. \fB\-\-par=\fIPath::Name\fR). Most options can appear several
times and are processed in the order they appear in the command
line. The two positional parameters (\fIinput.xml\fR and
\fIoutput.fits\fR) can appear anywhere in the command line, except if
they start with a minus character (\-) in which case they must appear
last, after the option \fB\-\-\fR.

.SS Getting help
.IP \fB\-\-help\fR[=\fIclass\fR]
.PD 0
.IP \fB\-h\fR[\fIclass\fR]
Without argument \fIclass\fR, print help summary. Although not as
verbose as this manual page, the output of \fBgyoto \fI\-h\fR may be
more complete and up to date. If \fIclass\fR is specified, list and
document the properties of \fIclass\fR (e.g. "Screen",
"Astrobj::Star"). Then exit the program, unless \fB\-\-list\fR below
has only been specified.
.PD

.PD 0
.IP \fB\-\-list\fR
.IP \fB\-l\fR
Print list of currently registered Astrobj, Metric etc., then exit the
program. This occurs after loading \fIinput.xml\fR (if provided), so
that any plug-in specified in the input file have already been loaded.
.PD

.PD 0
.IP \fB\-\-version\fR
.IP \fB\-V\fR
Print the Gyoto version, ABI compatibility version, copyright
information and exit.
.PD

.SS Setting the verbosity level
Those options are processed separately from the other and take effect
early in the program execution.
.IP \fB\-\-silent\fR
.PD 0
.IP \fB\-s\fR
No output.
.PD
.IP \fB\-\-quiet\fR
.PD 0
.IP \fB\-q\fR
Minimal output.
.PD
.IP \fB\-\-verbose\fR[=\fIN\fR]
.PD 0
.IP \fB\-v\fR[\fIN\fR]
Verbose mode. Verbosity level \fIN\fR may be specified.
.PD
.IP \fB\-\-debug\fR
.PD 0
.IP \fB\-d\fR
Insanely verbose.
.PD
.IP \fB\-\-no\-sigfpe\fR
Do not try to raise SIGFPE upon arithmetic exceptions. This option is
meaningful only if fenv.h support is built in. Else this option is a
no-op as SIGFPE is never raised.

.SS Loading plug-ins
.IP \fB\-\-plugins\fR[=\fI[nofail:]plug1[,[nofail:]plug2][...]]\fR
.PD 0
.IP \fB\-p\fI[[nofail:]plug1[,[nofail:]plug2][...]]\fR
Comma-separated list of Gyoto plugins to load. Overrides GYOTO_PLUGINS
environment variable below. Only the last occurrence matters.
.PD
.SS Selecting a region
It is possible to ray-trace only part of the scenery by providing the
pixel coordinates of the bottom-left (\fIi0\fR, \fIj0\fR) and
top-right (\fIi1\fR, \fIj1\fR) corners of the region. The bottom-left
pixel of the complete image has coordinates i=1 and j=1. The step in
each direction (\fIdi\fR, \fIdj\fR) can also be specified.
.IP \fB\-\-ispec\fR=\fI[i0]:[i1]:[di]\fR
.PD 0
.IP \fB\-i\fI[i0]:[i1]:[di]\fR
.IP \fB\-\-jspec\fR=\fI[j0]:[j1]:[dj]\fR
.IP \fB\-j\fI[j0]:[j1]:[dj]\fR
Default values: \fIx0\fR: 1; \fIx1\fR: \fInpix\fR (see option
\fB\-\-resolution\fR below); \fIdx\fR: 1.
.PD
.IP \fB\-\-ispec\fR=\fIN\fR
.PD 0
.IP \fB\-i\fIN\fR
.IP \fB\-\-jspec\fR=\fIN\fR
.IP \fB\-j\fIN\fR
Set both \fIx0\fR and \fIx1\fR to \fIN\fR.
.PD
.SS Alternate region-selection options:
Those options are still supported for backward compatibility. They are
deprecated in favour of \fB\-\-ispec\fR and \fB\-\-jspec\fR above:
.IP \fB\-\-imin\fR=\fIi0
Default value: 1.
.IP \fB\-\-imax\fR=\fIi1
Default value: \fInpix\fR (see option \fB\-\-resolution\fR below).
.IP \fB\-\-di\fR=\fIdi
Default value:1.
.IP \fB\-\-jmin\fR=\fIj0
Default value: 1.
.IP \fB\-\-jmax\fR=\fIj1
Default value: \fInpix\fR (see option \fB\-\-resolution\fR below).
.IP \fB\-\-dj\fR=\fIdj
Default value:1.

.SS Setting the camera position
The following parameters are normally provided in the Screen section
of \fIinput.xml\fR but can be overridden on the command line for
instance to make a movie (by calling \fBgyoto\fR for each movie frame,
changing only the option \fB\-\-time\fR).
.IP \fB\-\-time\fR=\fItobs
The observing time in geometrical units.
.IP \fB\-\-fov\fR=\fIangle\fR
The field-of-view of the camera, in radians.
.IP \fB\-\-resolution\fR=\fInpix\fR
.PD 0
.IP \fB\-r\fInpix\fR
.PD
Number of rows and columns in the output image.
.IP \fB\-\-distance\fR=\fIdist\fR
(Coordinate) distance from the observer to the center of the
coordinate system, in geometrical units.
.IP \fB\-\-paln\fR=\fIOmega\fR
Position angle of the line of nodes, in radians, East of North. The is
the angle between the North direction and the line of nodes (see
below).
.IP \fB\-\-inclination\fR=\fIi\fR
Angle between the plane of the sky and the equator of the coordinate
system. The intersection of those two planes is the line of nodes.
.IP \fB\-\-argument\fR=\fItheta\fR
Angle in the equatorial plane between the line of nodes and one of the
main axes of the coordinate system.

.SS Miscellaneous
Unsorted option(s):
.IP \fB\-\-
Ends option processing, in case either \fIinput.xml\fR or
\fIoutput.fits\fR starts with "\-".
.IP \fB\-\-nthreads\fR=\fInth\fR
.PD 0
.IP \fB\-T\fInth\fR
.PD
Number of parallel threads to use. For instance, on a dual-core
machine, \fB\-\-nthreads\fR=2 should yield the fastest
computation. This option is silently ignored if Gyoto was compiled
without POSIX threads support. Note that the metric and object are
replicated for each thread which can lead to a decrease in performance
if either is memory-intensive. Setting this option to 0 is equivalent
to setting it to 1.
.IP \fB\-\-nprocesses\fR=\fInworkers\fR
.PD 0
.IP \fB\-P\fInworkers\fR
.PD
Number of MPI processes to spawn for parallel ray-tracing, in addition
to the main gyoto process which remains for managing the
computation. Ignored if gyoto was compiled without MPI
support. \fInworkers\fR is the number of workers spawned. The total
number of processes is \fInprocs\fR=\fInworkers\fR+1.  \fB-P\fR0
disables MPI multi-processing, while \fB\-P\fR1 uses two processes:
the manager and one worker. If \fInworkers\fR is >0, \-\-nthreads is
ignored. Note that the MPI environment usually needs to be set-up
using some variant of
.BR mpirun (1).
If \fBmpirun\fR starts several instances of \fBgyoto\fR,
\fInworkers\fR must be >0, but its exact value is ignored as the set
of processes used is exactly that launched by \fBmpirun\fR. In other
words, Gyoto can be called in a number of ways that should be
functionally equivalent:
.
.RS
.IP \(bu 4
let \fBmpirun\fR launch \fInprocs\fR instances of the \fBgyoto\fR
executable:
.IP
\fBmpirun\fR \-np \-P\fInprocs\fR \fBgyoto\fR \-P1 \fIinput.xml\fR
\fIoutput.fits\fR
.IP \(bu 4
let \fBmpirun\fR launch 1 instance of the \fBgyoto\fR executable, and
Gyoto spawn \fInworkers\fR worker processes:
.IP
\fBmpirun\fR \-np 1 \fBgyoto\fR \-P\fIworkers\fR \fIinput.xml\fR
\fIoutput.fits\fR
.IP \(bu 4
let \fBmpirun\fR launch 1 instance of the \fBgyoto\fR executable, and
\fInworkers\fR worker processes:
.IP
\fBmpirun\fR \-np 1 \fBgyoto\fR \-P1\fR \fIinput.xml\fR \fIoutput.fits\fR : \\
       \-np \fInworkers\fR \fBgyoto-mpi-worker.\fIversion\fR
.IP
where \fIversion\fR is the ABI compatibility version of \fBgyoto\fR
(see \fBgyoto\fR \-\-version).
.RE
.
.IP \fB\-\-impact\-coords\fR[=\fIimpactcoords.fits\fR]
In some circumstances, you may want to perform several computations in
which the computed geodesics end up being exactly identical. This is
the case for instance if you want to experiment changing the spectrum
of a star or when making a movie of a rotating, optically thick
disk. This option provides a mechanism to not recompute the geodesics
in the most simple case:
.
.RS
.IP \(bu 4
the Screen is always at the same position;
.IP \(bu 4
the Metric is always exactly the same;
.IP \(bu 4
the Astrobj is optically thick (no radiative transfer processing is
necessary);
.IP \(bu 4
the location and shape of the Astrobj is always the same.
.RE
.
.IP
If \fB\-\-impact\-coords\fR is passed without specifying
\fIimpactcoords.fits\fR, the 8-coordinate vectors of the object and
photon at impact point are saved for each point of the Screen. Missing
data (no impact) are set to DBL_MAX. These data are saved as a
supplementary image HDU in the FITS file which is identified by its
EXTNAME: "Gyoto Impact Coordinates". The FITS keyword "HIERARCH Gyoto
Observing Date" of this HDU holds the observing date (in geometrical
unit).
.IP
If \fIimpactcoords.fits\fR is specified, the above mentioned data are
read back from this file. The ray-tracing is not performed, but the
Gyoto::Astrobj::Generic::processHitQuantities() method is called
directly, yielding the same result if the four conditions above are
met. The observing date stored in the FITS keyword "HIERARCH Gyoto
Observing Date" is compared to the date specified in the screen or
using the \fB\-\-time\fR option and the impact coordinates are shifted
in time accordingly.
.IP
It is also possible to set the two versions of this option at the same time:
.RS
.PD 0
.IP
\fB\-\-impact\-coords\fR=\fIimpactcoords.fits\fR \fB\-\-impact\-coords\fR
.RE
.IP
In this case, the impact coordinates are read from
\fIimpactcoords.fits\fR, shifted in time, and saved in
\fIoutput.fits\fR.
.PD
.IP \fB\-\-unit\fR[=\fIunit\fR]
.PD 0
.IP \fB\-u\fR[\fIunit\fR]
.PD
Specify unit to use for allowing instances of \fB\-\-parameter\fR,
until next instance of \fB\-\-unit\fR.
.IP \fB\-\-parameter\fR=\fIPath::Name\fR[=\fIvalue\fR]
.PD 0
.IP \fB\-E\fIPath::Name\fR[=\fIvalue\fR]
.PD
Set arbitrary parameter by name. Parameters can be set in the Astrobj,
Metric etc. using the \fIPath\fR componenent. For instance,

For instance, assuming the Astrobj in \fIstar.xml\fR
has a property named "Radius" that can be set in unit "km", and a property named "Spectrum" which has a property named "Temperature", we can set the radius, temperature and the quantities to compute (a property in the Scenery itself) with:
.RS 10
\fBgyoto\fR \-EQuantities=Spectrum \\
.br
      \-ukm \-EAstrobj::Radius=3 \\
.br
      \-u \-EAstrobj::Spectrum::Temperature=1000 \\
.br
      star.xml star.fits

\fBgyoto\fR \-\-parameter=Quantities=Spectrum \\
.br
      \-\-unit=km \-\-parameter=Astrobj::Radius=3 \\
.br
      \-\-unit="" \-\-param=Astrobj::Spectrum::Temperature=1000 \\
.br
      star.xml star.fits

.RE


.IP \fB\-\-xmlwrite\fR=\fIoutput.xml\fR
.PD 0
.IP \fB\-X\fIoutput.xml\fR
.PD
Write back scenery to an XML file. The new file will contain
additional default parameters and reflect the effect of
\fB\-\-(astrobj|metric|scenery|screen|spectrometer)-parameter\fR that
appear before \fB\-\-xmlwrite\fR. Can appear several times, e.g. to
generate several XML files with different settings.

.SH FILES
.IP \fIinput.xml
A gyoto input file in XML format. Several examples are provided in the
source doc/examples directory. Depending on how you installed
\fBgyoto\fR, they may be installed on your system in a place such as
\fI/usr/share/doc/libgyoto/examples/\fR. It goes beyond the scope of
this manpage to document the XML file format supported by Gyoto,
please refer to the library documentation which may be distributed by
your package manager, can be compiled from the Gyoto source, and can
be consulted online at \fIhttp://gyoto.obspm.fr/\fR.
.IP \fIoutput.fits
The output image in FITS format. \fBgyoto\fR will not overwrite
\fIoutput.fits\fR unless it is prefixed with an (escaped) "!": "gyoto
in.xml \\!out.fits". This file may actually consist in a stack of
images depending on the Gyoto Quantities and on the Spectrometer
specified in \fIinput.xml\fR. For further information on the FITS
format, see \fIhttp://fits.gsfc.nasa.gov/\fR.
.SH ENVIRONMENT
.IP GYOTO_PLUGINS
Gyoto astronomical objects and metrics are implemented in plug-ins. To
use more (or less!) than the standard plug-ins, you may set the
environment variable GYOTO_PLUGINS to a comma-separated list of
plug-ins. \fBgyoto\fR will exit with an error status if unable to load
a specified plug-in, unless it is prefixed with "nofail:" in
GYOTO_PLUGINS. This environment variable is overridden by he
\fB\-\-plugins\fR command-line parameter. Default value:
"stdplug,nofail:lorene". Gyoto attempts to find plug-ins first by
relying on the system's dynamic linker (so paths in
e.g. LD_LIBRARY_PATH and ld.so.conf are searched first). If that
fails, it looks in PREFIX/lib/gyoto/ and finally in
PREFIX/lib/gyoto/SOVERS/ where PREFIX and SOVERS are two compile-time
options. PREFIX usually is /usr/local or /usr. At the time of writing,
SOVERS is 0.0.0.
.SH EXIT STATUS
\fBgyoto\fR returns \fB0\fR upon success, \fB1\fR if unable to parse
the command line or to interpret \fIinput.xml\fR, and a CFITSIO error
code if an error occurs when trying to open, write to, or close
\fIoutput.fits\fR. Refer to the CFITSIO documentation for more
details.
.SH AUTHOR
Thibaut Paumard <thibaut.paumard@obspm.fr> wrote this manual.
.SH "SEE ALSO"
.BR gyotoy (1)