Provided by: gyoto-bin_2.0.2-1.1build3_amd64 
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. The Python flavor to use can be controlled through the
GYOTO_PYTHON environment variable.
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.
GYOTO_PYTHON
The name of the Python plug-in to use for mk-video (typically either "python3" or a
more specific version such as "python3.12"). By default several names are tried.
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)