Provided by: gyoto-bin_1.4.4-8build2_amd64 bug

NAME

       Gyoto - the General relativitY Orbit Tracer of Observatoire de Paris

SYNOPSIS

       gyoto [--silent|--quiet|--verbose[=N]|--debug]
             [--no-sigfpe]
             [--help[=class]] [--version] [--list]
             [--ispec=i0:i1:di] [--jspec=j0:j1:dj]
             ([--imin=i0] [--imax=i1] [--di=di])
             ([--jmin=j0] [--jmax=j1] [--dj=dj])
             [--time=tobs] [--tmin=tmin]
             [--fov=angle] [--resolution=npix] [--distance=dist]
             [--paln=Omega] [--inclination=i] [--argument=theta]
             [--nthreads=nth] [--nprocesses=nworkers]
             [--plugins=pluglist]
             [--impact-coords[=fname.fits]]
             [--unit[=unit]]
             [--parameter=Path::Name[=value]]
             [--xmlwrite=output.xml]
             [--] input.xml output.fits

       gyoto mk-video [options]

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.

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

       In  the  second  form,  gyoto  produces a movie. See gyoto mk-video --help for details. In
       particular, it can read a Scenery in XML format and a trajectory also in XML  format  (for
       instance  produced  with  gyotoy(1), see below) and produce a movie as would be seen by an
       observer following this trajectory. The Gyoto plug-in python and the Python module OpenCV-
       Python must be installed.

       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

       The gyoto program accepts many options. Most have a long name  (e.g.  --parameter)  and  a
       short  name  (e.g.  -E).  When  an  option  takes  an  argument, this argument must follow
       immediately the short option (e.g. -EPath::Name) and be separated from the long option  by
       exactly  the  character "=" (e.g. --parameter=Path::Name). Long options can be abbreviated
       as long as the abbreviation is  unambiguous  (e.g.  --par=Path::Name).  Most  options  can
       appear  several  times and are processed in the order they appear in the command line. The
       two positional parameters (input.xml and output.fits) 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 --.

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

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

       --version
       -V     Print the Gyoto version, ABI compatibility version, copyright information and exit.

   Setting the verbosity level
       Those options are processed separately from the other and take effect early in the program
       execution.

       --silent
       -s     No output.

       --quiet
       -q     Minimal output.

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

       --debug
       -d     Insanely verbose.

       --no-sigfpe
              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.

   Loading plug-ins
       --plugins[=[nofail:]plug1[,[nofail:]plug2][...]]
       -p[[nofail:]plug1[,[nofail:]plug2][...]]
              Comma-separated  list of Gyoto plugins to load. Overrides GYOTO_PLUGINS environment
              variable below. Only the last occurrence matters.

   Selecting a region
       It is 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. The step in each  direction  (di,
       dj) can also be specified.

       --ispec=[i0]:[i1]:[di]
       -i[i0]:[i1]:[di]
       --jspec=[j0]:[j1]:[dj]
       -j[j0]:[j1]:[dj]
              Default values: x0: 1; x1: npix (see option --resolution below); dx: 1.

       --ispec=N
       -iN
       --jspec=N
       -jN    Set both x0 and x1 to N.

   Alternate region-selection options:
       Those  options  are  still  supported  for  backward compatibility. They are deprecated in
       favour of --ispec and --jspec above:

       --imin=i0
              Default value: 1.

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

       --di=di
              Default value:1.

       --jmin=j0
              Default value: 1.

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

       --dj=dj
              Default value:1.

   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
       -rnpix 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):

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

       --nthreads=nth
       -Tnth  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.

       --nprocesses=nworkers
       -Pnworkers
              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. nworkers is the number of workers spawned. The total
              number of processes is nprocs=nworkers+1.  -P0 disables MPI multi-processing, while
              -P1  uses  two processes: the manager and one worker. If nworkers is >0, --nthreads
              is ignored. Note that the MPI environment usually needs to  be  set-up  using  some
              variant  of  mpirun(1).  If mpirun starts several instances of gyoto, nworkers must
              be >0, but its exact value is ignored as the set of processes used is exactly  that
              launched  by  mpirun.  In other words, Gyoto can be called in a number of ways that
              should be functionally equivalent:

              •   let mpirun launch nprocs instances of the gyoto executable:

                  mpirun -np -Pnprocs gyoto -P1 input.xml output.fits

              •   let mpirun launch 1 instance of the gyoto executable, and Gyoto spawn  nworkers
                  worker processes:

                  mpirun -np 1 gyoto -Pworkers input.xml output.fits

              •   let  mpirun  launch  1  instance  of  the gyoto executable, and nworkers worker
                  processes:

                  mpirun -np 1 gyoto -P1 input.xml output.fits : \
                         -np nworkers gyoto-mpi-worker.version

                  where version is the ABI compatibility version of gyoto (see gyoto --version).

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

       --unit[=unit]
       -u[unit]
              Specify unit to use for allowing instances of --parameter, until next  instance  of
              --unit.

       --parameter=Path::Name[=value]
       -EPath::Name[=value]
              Set  arbitrary parameter by name. Parameters can be set in the Astrobj, Metric etc.
              using the Path componenent. For instance,

              For instance, assuming the Astrobj in star.xml 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:
                 gyoto -EQuantities=Spectrum \
                       -ukm -EAstrobj::Radius=3 \
                       -u -EAstrobj::Spectrum::Temperature=1000 \
                       star.xml star.fits

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

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

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 overridden by 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.

SEE ALSO

       gyotoy(1)