Provided by: gyoto-bin_1.2.0-4_amd64 bug

NAME

       Gyoto - the General relativitY Orbit Tracer of Observatoire de Paris

SYNOPSIS

       gyoto [--silent|--quiet|--verbose[=N]|--debug]
             [--no-sigfpe]
             [--help[=class]] [--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=nprocs]
             [--plugins=pluglist]
             [--impact-coords[=fname.fits]]
             [--unit[=unit]]
             [--parameter=Path::Name[=value]]
             [--xmlwrite=output.xml]
             [--] 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

       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.

   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=nprocs
       -Pnprocs
              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. nprocs is the number of workers spawned. -P0 disables
              MPI multi-processing, while -P1 uses two processes: the manager and one worker.  If
              nprocs is >0, --nthreads is ignored. Note that the MPI environment usually needs to
              be set-up using some variant of mpirun(1).  You  should  usually  only  launch  one
              instance of gyoto, and either let it spawn its workers (using MPI_Comm_spawn(3)) or
              tell mpirun to do so:

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

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

              However, under Open MPI, gyoto also supports the more traditional:

                     mpirun -np nprocs gyoto input.xml output.fits

              In this case, this option (--nprocesses/-P) is ignored.

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