.\" Process this file with .\" groff -man -Tascii foo.1 .\" .TH GYOTO 1 "AUGUST 2013" 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\-\-imin\fR=\fIi0\fR] [\fB\-\-imax\fR=\fIi1\fR] [\fB\-\-jmin\fR=\fIj0\fR] [\fB\-\-jmax\fR=\fIj1\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\-\-plugins\fR=\fIpluglist\fR] [\fB\-\-impact-coords\fR[=\fIfname.fits\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 .IP \fB\-\- Ends option processing, in case either \fIinput.xml\fR or \fIoutput.fits\fR starts with "\-". .SS Setting the verbosity level .IP \fB\-\-silent\fR No output. .IP \fB\-\-quiet\fR Minimal output. .IP \fB\-\-verbose\fR[=\fIN\fR] Verbose mode. Verbosity level \fIN\fR may be specified. .IP \fB\-\-debug\fR Insanely verbose. .SS Choosing plug-ins .IP \fB\-\-plugins\fR=\fI[nofail:]plug1[,[nofail:]plug2][...] Comma-separated list of Gyoto plugins to load. Overwrites GYOTO_PLUGINS environment variable below. .SS Selecting a region It's 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. .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\-\-jmin\fR=\fIj0 Default value: 1. .IP \fB\-\-jmax\fR=\fIj1 Default value: \fInpix\fR (see option \fB\-\-resolution\fR below). .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 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\-\-nthreads\fR=\fInth\fR 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\-\-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 directy, 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: .IP \fB\-\-impact\-coords\fR=\fIimpactcoords.fits\fR \fB\-\-impact\-coords\fR .IP In this case, the impact coordinates are read from \fIimpactcoords.fits\fR, shifted in time, and saved in \fIoutput.fits\fR. .RE .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 overwritten byt 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 wrote this manual. .SH "SEE ALSO" .BR gyotoy (1)