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 --.
Gettinghelp--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.
Settingtheverbositylevel
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.
Loadingplug-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.
Selectingaregion
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.
Alternateregion-selectionoptions:
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.
Settingthecameraposition
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 -Pnprocsgyoto -P1 input.xmloutput.fits
• let mpirun launch 1 instance of the gyoto executable, and Gyoto spawn nworkers worker
processes:
mpirun -np 1 gyoto -Pworkersinput.xmloutput.fits
• let mpirun launch 1 instance of the gyoto executable, and nworkers worker processes:
mpirun -np 1 gyoto -P1 input.xmloutput.fits : \
-np nworkersgyoto-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.
Install Now
PNG Icons
