Ubuntu Manpage: Gyoto - the General relativitY Orbit Tracer of Observatoire de Paris

NAME

       Gyoto - the General relativitY Orbit Tracer of Observatoire de Paris

SYNOPSIS

       gyoto [--silent|--quiet|--verbose[=N]|--debug]
             [--imin=i0] [--imax=i1] [--jmin=j0] [--jmax=j1]
             [--time=tobs] [--tmin=tmin]
             [--fov=angle] [--resolution=npix] [--distance=dist]
             [--paln=Omega] [--inclination=i] [--argument=theta]
             [--nthreads=nth] [--plugins=pluglist]
             [--impact-coords[=fname.fits]]
             [--] input.xml output.fits

DESCRIPTION

       Gyoto  is  a  framework  for  computing geodesics in curved space-times. The gyoto 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.

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

       A  companion  program, gyotoy(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 --jmin option.

OPTIONS

-- Ends option processing, in case either input.xml or output.fits starts with "-".

Setting the verbosity level
--silent
No output.

--quiet
Minimal output.

--verbose[=N]
Verbose mode. Verbosity level N may be specified.

--debug
Insanely verbose.

Choosing plug-ins
--plugins=[nofail:]plug1[,[nofail:]plug2][...]
Comma-separated list of Gyoto plugins to load. Overwrites GYOTO_PLUGINS environment
variable below.

Selecting a region
It's possible to ray-trace only part of the scenery by providing the pixel coordinates of
the bottom-left (i0, j0) and top-right (i1, j1) corners of the region. The bottom-left
pixel of the complete image has coordinates i=1 and j=1.

--imin=i0
Default value: 1.

--imax=i1
Default value: npix (see option --resolution below).

--jmin=j0
Default value: 1.

--jmax=j1
Default value: npix (see option --resolution below).

Setting the camera position
The following parameters are normally provided in the Screen section of input.xml but can
be overridden on the command line for instance to make a movie (by calling gyoto for each
movie frame, changing only the option --time).

--time=tobs
The observing time in geometrical units.

--fov=angle
The field-of-view of the camera, in radians.

--resolution=npix
Number of rows and columns in the output image.

--distance=dist
(Coordinate) distance from the observer to the center of the coordinate system, in
geometrical units.

--paln=Omega
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).

--inclination=i
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.

--argument=theta
Angle in the equatorial plane between the line of nodes and one of the main axes of
the coordinate system.

Miscellaneous
Unsorted option(s):

--nthreads=nth
Number of parallel threads to use. For instance, on a dual-core machine,
--nthreads=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.

--impact-coords[=impactcoords.fits]
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:

• the Screen is always at the same position;

• the Metric is always exactly the same;

• the Astrobj is optically thick (no radiative transfer processing is necessary);

• the location and shape of the Astrobj is always the same.

If --impact-coords is passed without specifying impactcoords.fits, 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).

If impactcoords.fits 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 --time option and the impact coordinates are shifted in
time accordingly.

It is also possible to set the two versions of this option at the same time:

--impact-coords=impactcoords.fits --impact-coords

In this case, the impact coordinates are read from impactcoords.fits, shifted in
time, and saved in output.fits.

FILES

       input.xml
              A gyoto input file in XML format. Several  examples  are  provided  in  the  source
              doc/examples directory. Depending on how you installed gyoto, they may be installed
              on your system in a place such as /usr/share/doc/libgyoto/examples/. 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
              http://gyoto.obspm.fr/.

       output.fits
              The output image in FITS format. gyoto will not overwrite output.fits 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  input.xml. For further information on the FITS format,
              see http://fits.gsfc.nasa.gov/.

ENVIRONMENT

       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. gyoto 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  --plugins
              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.

EXIT STATUS

       gyoto returns 0 upon success, 1 if unable to  parse  the  command  line  or  to  interpret
       input.xml,  and  a CFITSIO error code if an error occurs when trying to open, write to, or
       close output.fits. Refer to the CFITSIO documentation for more details.

AUTHOR

       Thibaut Paumard <thibaut.paumard@obspm.fr> wrote this manual.